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About this Book 


The Presentation Manager Programming Reference is a detailed technical reference, in three 
volumes, for application programmers creating programs using the Presentation Manager interface. 

Chapter 1 contains important information. You should read it before using this book. 

This reference does not give guidance on how to use the functions, nor does it contain information 
about how the functions are related to each other. It is intended to be used in conjunction with the 
Programming Guide Volumes II and III. 


Prerequisite Knowledge 

The OS/2 2.0 Technical Library is intended for professional application developers knowledgeable in 
at least one programming language in which OS/2 programs can be written. The information in the 
Technical Library assumes that you are new to programming with OS/2 and the Presentation 
Manager. You should understand the OS/2 services available to users. 


Related Publications 

The Application Design Guide and the Programming Guide Volumes I, II, and III introduce the 
programming concepts that you should understand before you begin developing applications to run 
on the OS/2 operating system. Getting Started describes the online programming books, tools, 
programming aids, and sample programs that make up the IBM Developer's Toolkit for OS/2 2.0. 


Organization of this Book 

This book is in three volumes. The contents of each volume are as follows: 

Volume I (Functions) 

Chapter 1, “Introduction” on page 1-1 

You should read this chapter before using this book. 

Chapter 2, “Device Functions” on page 2-1 

Chapter 3, “Direct Manipulation Functions” on page 3-1 

Chapter 4, “Dynamic Data Formatting Functions” on page 4-1 

Chapter 5, “Graphics Functions” on page 5-1 

Chapter 6, “Profile Functions” on page 6-1 

Chapter 7, “Spooler Functions” on page 7-1 

Volume II (Functions and Workplace) 

Chapter 8, “Window Functions” on page 8-1 

Chapter 9, “Workplace Classes, Instance Methods, and Class Methods” on page 9-1 
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Volume III (Related Information and Data Types) 

Chapter 10, “Functions Supplied by Applications” on page 10-1 

Chapter 11, “Introduction to Message Processing” on page 11-1 

Chapter 12, “Default Window Procedure Message Processing” on page 12-1 

Chapter 13, “Button Control Window Processing” on page 13-1 

Chapter 14, “Entry Field Control Window Processing” on page 14-1 

Chapter 15, “Frame Control Window Processing” on page 15-1 

Chapter 16, “List Box Control Window Processing” on page 16-1 

Chapter 17, “Menu Control Window Processing” on page 17-1 

Chapter 18, “Multi-Line Entry Field Control Window Processing” on page 18-1 

Chapter 19, “Prompted Entry Field Control Window Processing” on page 19-1 

Chapter 20, “Scroll Bar Control Window Processing” on page 20-1 

Chapter 21, “Spin Button Control Window Processing” on page 21-1 

Chapter 22, “Static Control Window Processing” on page 22-1 

Chapter 23, “Title Bar Control Window Processing” on page 23-1 

Chapter 24, “Container Control Window Processing” on page 24-1 

Chapter 25, “Notebook Control Window Processing” on page 25-1 

Chapter 26, “Slider Control Window Processing” on page 26-1 

Chapter 27, “Value Set Control Window Processing” on page 27-1 

Chapter 28, “Clipboard Messages” on page 28-1 

Chapter 29, “Direct Manipulation (Drag) Messages” on page 29-1 

Chapter 30, “Dynamic Data Exchange Messages” on page 30-1 

Chapter 31, “Help Manager Messages” on page 31-1 

Chapter 32, “Resource Files” on page 32-1 

Chapter 33, “Graphics Orders” on page 33-1 
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Chapter 34, “Code Pages” on page 34-1 


Appendix A, “Data Types” on page A-1 
Appendix B, “Error Codes” on page B-1 
Appendix C, “Error Explanations” on page C-1 
Appendix D, “Standard Bit-Map Formats” on page D-1 
Appendix E, “Fonts Supplied with OS/2” on page E-1 
Appendix F, “The Font-File Format” on page F-1 
Appendix G, “Format of Interchange Flies” on page G-1 
Appendix H, “Initialization File Information” on page H-1 
Appendix I, “Virtual Key Definitions” on page 1-1 
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Notices 


References in this publication to IBM products, programs, or services do not imply that IBM intends 
to make these available in all countries in which IBM operates. Any reference to an IBM product, 
program or service is not intended to state or imply that only IBM's product, program, or service may 
be used. Any functionally equivalent product, program, or service that does not infringe any of IBM's 
intellectual property rights or other legally protectible rights may be used instead of the IBM product, 
program, or service. Evaluation and verification of operation in conjunction with other products, 
programs, or services, except those expressly designated by IBM, are the user's responsibility. 

IBM may have patents or pending patent applications covering subject matter in this document. The 
furnishing of this document does not give you any license to these patents. You can send license 
inquiries, in writing, to the IBM Director of Commercial Relations, IBM Corporation, Purchase, NY 
10577. 

The following terms, denoted by an asterisk^) in this publication, are trademarks of the IBM 
Corporation in the United States and/or other countries: 

IBM 

Common User Access 
CUA 
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OS/2 
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SAA 

System Application Architecture 

The following terms, denoted by a double asterisk (**) in this publication, are trademarks of other 


companies as follows: 
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Adobe Systems Incorporated 
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Linotype AG 

LaserJet 

Hewlett-Packard Company 

Intel 

Intel Corporation 

Microsoft 

Microsoft Corporation 
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Adobe Systems Incorporated 

Times New Roman 

Monotype Corporation 

Windows 

Microsoft Corporation 
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Chapter 1. Introduction 


This chapter contains important information. Read it before using this book. 

The purpose of this reference is to give important information about functions, messages, constants, 
error codes, and data types. It provides language-dependent information about the functions which 
enables the user to generate call statements in C Language. 

The following information is provided: 

• The parameter list for each function. 

• The syntax of each data type and structure 


Notation Conventions 


The following notation conventions are used in this reference: 


NULL 

NULLHANDLE 
Implicit Pointer 


Constant Names 


The term NULL applied to a parameter is used to indicate the presence of the 
pointer parameter, but with no value. 

The term NULLHANDLE applied to a parameter is used to indicate the presence 
of the handle parameter, but with no value. 

If no entry for a data type “Pxxxxxxx” is found in Appendix A, “Data Types” on 
page A-1, then it is implicitly a pointer to the data type “xxxxxxx." See “Implicit 
Pointer Data Types” on page 1-5. 

All constants are written in uppercase. Where applicable, constant names have 
a prefix derived from the name of a function, message, or idea associated with 
the constant. For example: 

WM_CREATE Window message 

SV_CXICON System value 

CF_TEXT Clipboard format. 

In this reference, a set of constants with the same prefix is written as in these 
examples: 

Window message WM_* 

System value SV_* 


Conventions used in Function Descriptions 

The documentation of each function contains these sections: 

Function name The function name, listed in alphabetic order of C (long) name together with the 
English name. This is at the top of each page followed by the name of the define 
that calls the correct header files to be included, the function prototype, and a 
brief description of the function. 

Parameters Each parameter is listed with its data type and a brief description. 

There are four kinds of parameters: 

Input Specified by the programmer. 

Output Returned by the Presentation Manager* (PM) interface. 

Input/Output Specified by the programmer and modified by PM. 


* Trademark of IBM Corporation 
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Return The return values are shown, together with possible errors, or 

TRUE/FALSE indicators if a Boolean function. 

A list of possible errors (where appropriate) is included in this 
section. Some functions do not have error messages. 

Note: Data types are given in C. 

Remarks Additional information about the function, where required. 

Related Functions Functions that can be used with the described function. 

Example Code Example of how the function can be used. 

Note: The functions in this book are named in mixed-case for readability, but are known to the 

system as uppercase character strings. For example, the function “GpiBeginArea" is actually 
the external name “GPIBEGINAREA.” 

If you are using a compiler that generates a mixed-case external name, you should code the 
OS/2' functions in uppercase. 

Message Queues 

For some functions, the Remarks section of the function description includes a statement that the 
function requires a message queue. This means that, before issuing the call, WinCreateMsgQueue 
must be issued by the same thread. For other functions, no previous WinCreateMsgQueue is 
required, and it is only necessary to issue Winlnitialize from the same thread. 


Error Severities 

Each of the error conditions given in the list of errors for each call falls into one of these areas: 

Warning The function detected a problem, but took some remedial action that enabled 

the function to complete successfully. The return code in this case indicates 
that the function completed successfully. 

Error The function detected a problem for which it could not take any sensible 

remedial action. The system has recovered from the problem, and the state 
of the system with respect to the application remains the same as at the time 
when the function was requested. The system has not even partially 
executed the function (other than reporting the error). 

Severe Error The function detected a problem from which the system could not reestablish 

its state, with respect to the application, at the time when that function was 
requested; that is, the system partially executed the function. This, therefore, 
necessitates the application performing some corrective activity to restore 
the system to some known state. 

Unrecoverable Error The function detected some problem from which the system could not 

re-establish its state, with respect to the application, at the time when that 
call was issued. It is possible that the application cannot perform some 
corrective action to restore the system to some known state. 

The WinGetLastError and WinGetErrorlnfo functions can be used to find out more about an error (or 

warning) that occurs as a result of executing a call. 


' Trademark of IBM Corporation 
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Header Files 

All functions require an “include” for the system header file OS2.H: 
linclude <0S2.H> 

Also, most functions require a “define” to select an appropriate (conditional) section of the header 
file, and hence, the required entry point. Where this is necessary, it is shown at the head of the 
function definition in the form: 

Idefine INCL_name 

Note: These “#defines” must precede the “#include < OS2.H > 


Helper Macros 

A series of macros is defined for packing data into, and extracting data from, variables of MPARAM 
and MRESULT data types. They are used in conjunction with the WinSendMsg and the other 
message functions, and also inside window and dialog procedures. 

These macros always cast their arguments to the specified type, so values of any of the types 
specified for each macro may be passed without additional casting. NULL may be used to pass 
unused parameter data. 

Macros for packing data into a MPARAM variable: 


/* Used to pass any pointer type: */ 

Idefine MPFROMP(p) ((MPARAM) (VOID *)(p)) 

/* Used to pass a window handle: */ 

Idefine MPFROMHWND(hwnd) ((MPARAM) (HWND) (hwnd)) 

/* Used to pass a CHAR, UCHAR, or BYTE: */ 

Idefine MPFROMCHAR(ch) ( (MPARAM) (USHORT) (ch) ) 

/* Used to pass a SHORT, USHORT, or BOOL: */ 

Idefine MPFROMSHORT(s) ((MPARAM) (USHORT) (s)) 

/* Used to pass two SHORTs or USHORTs: */ 

Idefine MPFR0M2SH0RT (si, s2) ( (MPARAM)MAKELONG(sl, s2)) 

/* Used to pass a SHORT and 2 UCHARs: (WM_CHAR msg)*/ 
Idefine MPFR0MSH2CH(s, uchl, uch2) 

( ( MPARAM ) M AKELONG ( s , MAKESHORT(uchl, uch2))) 

/* Used to pass a LONG or ULONG: */ 

Idefine MPFR0ML0NG(1 ) ((MPARAM) (ULONG) (1)) 
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Macros for extracting data from a MPARAM variable: 


/* Used to get any pointer type: */ 

I define PVOIDFROMMP(mp) ((VOID *)(mp)) 


/* Used to get a window handle: */ 
Idefine HWNDFROMMP(mp) ( (HWND) (mp)) 


/* Used to get CHAR, UCHAR, or BYTE: */ 


Idefine CHARI FROMMP(mp) 
Idefine CHAR2FR0MMP(mp) 
Idefine CHAR3FR0MMP(mp) 
Idefine CHAR4FR0MMP(mp) 


( (UCHAR) (mp)) 

( (UCHAR) ((ULONG)mp » 8)) 

( (UCHAR) ((ULONG)mp » 16)) 
((UCHAR) ((ULONG)mp » 24) ) 


/* Used to get a SHORT, USHORT, or BOOL: */ 

Idefine SHORTlFROMMP(mp) ( (USHORT) (ULONG) (mp)) 

Idefine SH0RT2FR0MMP(mp) ( (USHORT) ((ULONG)mp » 16)) 


/* Used to get a LONG or ULONG: */ 
Idefine LONGFROMMP(mp) ((ULONG) (mp)) 


Macros for packing data into a M RESULT variable: 


/* Used to pass any pointer type: */ 

Idefine MRFROMP(p) ((MRESULT)(VOID *)(p)) 

/* Used to pass a SHORT, USHORT, or BOOL: */ 

Idefine MRFROMSHORT(s) ((MRESULT) (USHORT) (s)) 

/* Used to pass two SHORTs or USHORTs: */ 

Idefine MRFR0M2SH0RT(sl, s2) ( (MRESULT)MAKELONG(sl, s2)) 

/* Used to pass a LONG or ULONG: */ 

Idefine MRFROMLONG(l) ((MRESULT) (ULONG) (1)) 


Macros for extracting data from a MRESULT variable: 


/* Used to get any pointer type: */ 

Idefine PVOIDFROMMR(mr) ((VOID *)(mr)) 

/* Used to get a SHORT, USHORT, or BOOL: */ 

Idefine SHORTlFROMMR(mr) ( (USHORT) ((ULONG)mr)) 

Idefine SH0RT2FR0MMR(mr) ( (USHORT) ((ULONG)mr » 16)) 

/* Used to get a LONG or ULONG: */ 

Idefine LONGFROMMR(mr) ((ULONG) (mr)) 
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The following macros are for use with DDESTRUCT and DDEINIT structures: 


/* Used to return a PSZ pointing to the ODE item name: */ 

Idefine DDESJ’SZITEMNAME(pddes) \ 

( ( (PSZ) pddes) + ((PDDESTRUCT)pddes)->offszItemName) 

/* Used to return a PBYTE pointing to the DDE data: */ 

Idefine DDES_PABDATA(pddes) \ 

( ( (PBYTE)pddes) + ((PDDESTRUCT)pddes)->offabData) 

/* Used to convert a selector to a PDDESTRUCT: */ 

Idefine SELTOPDDES(sel) ((PDDESTRUCT)MAKEP(sel , 0)) 

/* Used to PDDESTRUCT to a selector for freeing / reallocating: */ 
Idefine PDDESTOSEL(pddes) (SELECTOROF(pddes) ) 

/* Used to PDDEINIT to a selector for freeing: */ 

Idefine PDDEITOSEL(pddei) (SELECTOROF(pddei)) 


Addressing Elements in Arrays 

Constants defining array elements are given values that are zero-based in C; that is, the numbering 
of the array elements starts at zero, not one. 

For example, in the DevQueryCaps function, the sixth element of the al Array parameter is 
CAPSJHEIGHT, which is equated to 5. 

Count parameters related to such arrays always mean the actual number of elements available. 
Therefore, again using the DevQueryCaps function as an example, if all elements up to and including 
CAPSJHEIGHT are provided for, ICount could besetto (CAPS_HEIGHT+ 1). 

In functions for which the starting array element can be specified, this is always zero-based, and so 
the C element number constants can be used directly. For example, to start with the CAPSJHEIGHT 
element, the IStart parameter can be set to CAPSJHEIGHT. 


Implicit Pointer Data Types 

A data type name beginning with “P” (for example, PERRORCODE) is likely to be a pointer to another 
datatype (in this instance, ERRORCODE). 

In the data type summary, Appendix A, “Data Types” on page A-1, no explicit “typedefs” are shown 
for pointers. Therefore, if no data type definition can be found in the summary for a data type name 
"Pxxxxxx,” it becomes a pointer to the datatype “xxxxxx,” for which a definition should be found in 
the summary. 

The implicit type definition needed for such a pointer “Pxxxxxx" is: 
typedef xxxxxx *Pxxxxxx; 

Such definitions are provided by means of the system header file OS2.H. 
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Storage Mapping of Data Types 

The storage mapping of the data types is dependent on the machine architecture. To be portable, 
applications must access the data types using the definitions supplied for that environment. 


Double-Byte Character Set (DBCS) 

Throughout this publication, you will see references to specific values for character strings. The 
values are for singie-byte character set (SBCS). If you use the double-byte character set (DBCS), 
note that one DBCS character equals two SBCS characters. 
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Chapter 2. Device Functions 

The following table shows all the Device (Dev) functions in alphabetic order. 


C Name 

DevCIoseDC 

DevEscape 

DevOpenDC 

DevPostDeviceModes 

DevQueryCaps 

DevQueryDeviceNames 

DevQueryHardcopyCaps 
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DevCIoseDC - 
Close Device Context 


#define INCL_DEV /* Or use INCL_PM. Also in COMMON section 7 


HMF DevCIoseDC (HDC hdc) 


This function closes a device context. 

Parameters 

hdc (HDC) - input 

Device-context handle. 


Returns 

Error indicator metafile handle (for a metafile device context) 

DEV_ERROR Error occurred. 

DEV_OK Device closed, but not a metafile device context. 

Other Device closed, a metafile device context whose metafile handle is returned. 

Possible returns from WinGetLastError 

PMERR_NOT_CREATED_BY_DEVOPENDC An attempt has been made to destroy a device context 

using DevCIoseDC that was not created using 
DevOpenDC. 

P M E R R DC IS ASSOCI ATED An attempt was made to associate a presentation space 

with a device context that was already associated or to 
destroy a device context that was associated. 

PMERR_INV_HDC An invalid device-context handle or (micro presentation 

space) presentation-space handle was specified. 

Remarks 

If the device context is currently associated with a presentation space, or if it is created with the 
WinOpenWindowDC call (that is, it is a screen device context), an error is raised, and the device 
context is not closed. 

If the device context being closed is a memory device context that has a bit map currently selected 
into it (see the GpiSetBitmap function), the bit map is automatically deselected before the device 
context is closed. 

Any clip region currently in use for this device context is deleted. 


Related Functions 

Prerequisite Functions 

• DevOpenDC 

Other Related Functions 

• WinOpenWindowDC 
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DevCIoseDC - 
Close Device Context 


Example Code 

This example calls DevCIoseDC to close a device context based on the handle returned from 
DevOpenDC. 

Idefine INCL_DEV /* Device Function definitions */ 

linclude <os2.h> 

HDC hdc; /* Device-context handle */ 

HMF hmf; /* error code (or metafile handle if 

metafile device context) */ 

/* close the device context associated with handle hdc */ 
hmf = DevCIoseDC (hdc) ; 
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DevEscape 

Escape 


#define INCL_DEV /* Or use INCL_PM */ 


LONG DevEscape (HDC hdc, LONG ICode, LONG IlnCount, PBYTE pblnData, 
PLONG piOutCount, PBYTE pbOutData) 


This function allows applications to access facilities of a device not otherwise available through the 
API. Escapes are, in general, sent to the presentation driver and must be understood by it. 


Parameters 

hdc (HDC) - input 

Device-context handle. 

ICode (LONG) - input 
Escape code. 

If the device context is of type OD_QUEUED with a PMQSTD spool file, some escapes are sent 
to the presentation driver and others are recorded in the spool file (depending on the escape 
code). If the device context is of type ODMETAFILE, all escapes are metafiled. If the device 
context is of any type other than OD_QUEUED (with a PM_Q_STD spool file) or OD METAFILE, all 
escapes are sent to the presentation driver. 

The description for each standard escape specifies which of these categories the escape falls 
into. 

Devices can define additional escape functions using user ICode values, that have the following 
ranges: 

32 768 through 40 959 Not metafiled and not recorded (sent to presentation driver for 
PM_Q_STD) 

40 960 through 49 151 Metafiled only (sent to presentation driver for PM Q STD) 

49 152 through 57 343 Metafiled and recorded (not sent to presentation driver) for PM_Q_STD 
57 344 through 65 535 Recorded only (not sent to presentation driver for PM Q STD). 

The following escapes are defined: 

DEVESCQUERYESCSUPPORT 
DEVESC_GETSCALINGF ACTOR 
DEVESCST ARTDOC 
DEVESCENDDOC 
DEVESCABORTDOC 
DEVESCNEWFRAME 
DE VESCR AWDAT A 
DEVESCQUERYVIOCELLSIZES 
DEVESCSETMODE 

IlnCount (LONG) - input 
Input data count. 

Number of bytes of data in the pblnData buffer. 

pblnData (PBYTE) - input 

The input data required for this escape. 

piOutCount (PLONG) - input/output 
Output data count. 

piOutCount is the number of bytes of data in the pbOutData buffer. 

If data is returned in pbOutData, piOutCount is updated to the number of bytes of data returned. 
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DevEscape - 
Escape 


pbOutData (PBYTE) - output 
Output data. 

pbOutData is a buffer that receives the output from this escape. If plOutCount is null, no data is 
returned. 


Returns 

Implementation error indicator: 

DEVESC_ERROR 
DEVESCNOTIMPLEMENTED 
DEV OK 


Error 

Escape not implemented for specified code 
OK. 


Possible returns from WinGetLastError 

PMERRINVESCAPECODE 

PMERRJNVHDC 

PMERR_INV_LENGTH_OR_COUNT 

PMERR_ESC_CODE_NOT_SUPPORTED 

P M E RR_INV_ESCAPE_DAT A 


An invalid code parameter was specified with DevEscape. 

An invalid device-context handle or (micro presentation 
space) presentation-space handle was specified. 

An invalid length or count parameter was specified. 

The code specified with DevEscape is not supported by 
the target device driver. 

An invalid data parameter was specified with DevEscape. 


Remarks 

The data fields for standard escapes are: 

DEVESC_QUERYESCSUPPORT Queries whether a particular escape is implemented by the 

presentation driver. The return value gives the result. 

This escape is not metafiled or recorded. 

IlnCount Number of bytes pointed to by pblnData. 
pblnData The buffer contains an escape code value 

specifying the escape function to be checked. 
plOutCount Not used; can be set to 0. 
pbOutData Not used; can be set to null. 

DEVESC_GETSCALINGFACTOR Returns the scaling factors for the x and y axes of a printing 

device. For each scaling factor, an exponent of two is put in 
pbOutData. Thus, the value 3 is used if the scaling factor is 8. 

Scaling factors are used by devices that cannot support 
graphics at the same resolution as the device resolution. 

This escape is not metafiled or recorded. 

IlnCount Not used; can be set to 0. 

pblnData Not used; can be set to null. 

plOutCount The number of bytes of data pointed to by 

pbOutData. On return, this is updated to the 
number of bytes returned. 

pbOutData The address of a SFACTORS structure, which on 
return contains the scaling factors for the x and y 
axes. 

DEVESC_STARTDOC Indicates that a new print job is starting. All subsequent output 

to the device context is spooled under the same job identifier 
until a DEVESC_ENDDOC occurs. 

A GpiAssociate function must be issued to associate the 
presentation space with the device context before issuing this 
escape. 
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DevEscape - 
Escape 


DEVESC_ENDDOC 


DEVESCABORTDOC 


DEVESCNEWFRAME 


DEVESCRAWDAT A 


This escape is metafiled but not recorded. 

IlnCount Number of bytes pointed to by pblnData. 
pblnData The buffer contains a null-terminated string, 
specifying the name of the document. 
plOutCount Not used; can be set to 0. 
pbOutData Not used; can be set to null. 

Ends a print job started by DEVESC_STARTDOC. 

This escape is metafiled but not recorded. 

IlnCount Not used; can be set to 0. 
pblnData Not used; can be set to null. 
plOutCount Set equal to 2. 

pbOutData The buffer contains a USHORT specifying the job 
identifier if a spooler print job is created. 

Aborts the current job, erasing everything the application has 
written to the device since the last DEVESC_STARTDOC, 
including the DEVESC_STARTDOC. 

This escape is metafiled but not recorded. 

IlnCount Not used; can be set to 0 
pblnData Not used; can be set to null 
plOutCount Not used; can be set to 0 
pbOutData Not used; can be set to null. 

Signals when an application has finished writing to a page and 
wants to start a new page. It is similar to GpiErase processing 
for a screen device context, and causes a reset of the attributes. 
This escape is used with a printer device to advance to a new 
page. 

This escape is metafiled and recorded. 

IlnCount Not used; can be set to 0 
pblnData Not used; can be set to null 
plOutCount Not used; can be set to 0 
pbOutData Not used; can be set to null. 

Allows an application to send data directly to a presentation 
driver. For example, in the case of a printer driver, this could 
be a printer data stream. 

If DEVESC_RAWDAT A is mixed with other data (such as GPI 
data) being sent to the same page of a device context, the 
results are unpredictable and depend upon the action taken by 
the presentation driver. For example, a presentation driver 
might ignore GPI data if DEVESC_RAWDAT A is mixed with it on 
the same page. In general, DE VESC_RAWDAT A should be sent 
either to a separate page (using the DEVESC_NEWFRAME 
escape to obtain a new page) or to a separate document (using 
the DE VESC_ST ARTDOC and DEVESC_EN D DOC escapes to 
create a new document). 

This escape is metafiled and recorded. 

IlnCount Number of bytes pointed to by pblnData 
pblnData Pointer to the raw data 
plOutCount Not used; can be set to 0 
pbOutData Not used; can be set to null. 
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DevEscape - 
Escape 


DEVESC_QUERYVIOCELLSIZES Returns the VIO cell sizes supported by the presentation driver. 

This escape is not metafiled or recorded. 

I InCount Not used; can be set to 0 

pblnData Not used; can be set to null. 

plOutCount The number of bytes of data pointed to by 

pbOutData. It must be an even multiple of the size 
in bytes of the LONG data type. On return, this is 
updated to the number of bytes returned. 
pbOutData The address of a buffer, which on return contains a 
VIOSIZECOUNT structure, immediately followed by 
count copies of a VIOFONTCELLSIZE structure. 

If plOutCount is less than the size of a LONG data 
type, plOutCount is updated to zero, and nothing is 
returned in the buffer pointed to by pbOutData. 

If plOutCount is equal to the size of a LONG data 
type, pbOutData returns the number of VIO cell 
sizes that can be returned by this escape. The 
buffer pointed to by pbOutData is updated so that 
maxcount is the number of VIO cell sizes that can 
be returned. 

If plOutCount is greater than the size of a LONG 
data type, pbOutData returns the VIO cell sizes that 
are supported. The buffer pointed to by pbOutData 
is updated so that: 

• maxcount is the number of VIO cell sizes that 
can be returned 

• count is the number of VIO cell sizes returned 
(may be zero if plOutCount is equal to twice the 
size of a LONG data type) 

• count copies of a VIOFONTCELLSIZE structure 
are returned. 

DEVESC_SETMODE Sets the printer into a particular mode. It is optional for printer 

drivers to support this escape, but those that do support it need 
to be aware of the code page of any built-in fonts. For example, 
if only code page 437 is built in, it is used if 437 is requested by 
DEVESC_SETMODE. However, if code page 865 is requested, a 
suitable code page/font could be downloaded. 

This escape is metafiled and recorded. 

IlnCount Number of bytes pointed to by pblnData 
pblnData Buffer contains an ESCSETMODE structure 
plOutCount Not used; can be set to 0 
pbOutData Not used; can be set to null. 


Related Functions 

Prerequisite Functions 

• DevOpenDC 

Other Related Functions 

• GpiAssociate(for DEVESC_STARTDOC) 

• GpiErase(for DEVESC_NEWFRAME) 
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DevEscape 

Escape 


Graphic Elements and Orders 

DevEscape functions generate orders only when metafiling. 
Order: Extended Escape 


Example Code 

This example uses DevEscape to access facilities of a device that would otherwise be unavailable 
through the normal Device API set. Here, a new page in a print job is started. 


Idefine INCL_DEV /* Device Function definitions */ 

linclude <os2.h> 


LONG 1 Result; 

HDC hdc; 

LONG plOutCount; 

PBYTE pbOutData; 


/* Error code or not implemented 

warning code */ 

/* Device-context handle */ 

/* length of output buffer ( i nput ) , 

number of bytes returned(output) */ 

/* output buffer */ 


/* for the NEWFRAME, input and output buffers are not used, 
so set the buffer lengths to zero(0) and set the buffers to 
NULL */ 

plOutCount = 0; 
pbOutData = NULL; 


1 Result = DevEscape(hdc, DEVESC_NEWFRAME, 0L, NULL, SplOutCount, 
pbOutData) ; 
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DevOpenDC - 
Open Device Context 


#define INCL_DEV /* Or use INCL_PM. Also in COMMON section */ 


HDC DevOpenDC (HAB hab, LONG IType, PSZ pszToken, LONG ICount, 
PDEVOPENDATA pdopData, HDC hdcComp) 


This function creates a device context. 


Parameters 

hab (HAB) - input 

Anchor-block handle. 

IType (LONG) - input 
Type of device context: 

A device, such as a printer or plotter, for which output is to be 
queued. 

Certain restrictions apply for this device type; see “Metafile 
Restrictions” on page G-1. 

A device, such as a printer or plotter, for which output is not to be 
queued. 

A device, such as a printer or plotter, but the device context is used 
only to retrieve information (for example, font metrics). Drawing 
can be performed to a presentation space associated with such a 
device context, but no output medium is updated. 

The device context is used to write a metafile. The presentation 
page defines the area of interest within the picture in the metafile. 
See OD_METAFILE_NOQUERY. 

Certain restrictions apply for this device type; see “Metafile 
Restrictions” on page G-1. 

OD_METAFILE_NOQUERY The device context is used to write a metafile. 

Functionally, this device type is the same as OD_METAFILE, except 
that querying of attributes is not allowed with a presentation space 
while it is associated with an OD_METAFILE_NOQUERY device 
context. If querying of attributes is not required, 
OD_METAFILE_NOQUERY should be used in preference to 
OD_METAFILE, since it gives improved performance. 

Certain restrictions apply for this device type; see “Metafile 
Restrictions” on page G-1. 

OD MEMORY A device context that is used to contain a bit map. The hdcComp 

parameter identifies a device with which the memory device 
context is to be compatible. 

pszToken (PSZ) - input 

Device-information token. 

This identifies the device information, held in the initialization file. This information is the same 
as that which may be pointed to by pdopData; any information that is obtained from pdopData 
overrides the information obtained by using this parameter. 

If pszToken is specified as “*”, no device information is taken from the initialization file. 

OS/2 behaves as if “*” is specified, but it allows any string. 


OD_QUEUED 

ODDIRECT 

ODJNFO 

ODMETAFILE 
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DevOpenDC - 
Open Device Context 


ICount(LONG) - input 
Number of items. 

This is the number of items present in the pdopData parameter. This can be less than the full list 
if omitted items are irrelevant, or are supplied from pszToken or elsewhere. 

pdopData (PDEVOPENDATA) - input 
Open-device-context data area. 

hdcComp (HOC) - input 

Compatible-device-context handle. 

When IType is ODMEMORY, this parameter is a handle to a device context compatible with bit 
maps that are to be used with this device context. 

If hdcComp is NULLHANDLE, compatibility with the screen is assumed. 


Returns 

Device-context handle: 

DEV_ERROR Error 
?40 Device-context handle. 

Possible returns from WinGetLastError 

P M E R R _INV_DC_T YPE 

PMERR_INV_LENGTH_OR_COUNT 
PM E R R_IN V_DC_D AT A 

PMERRJNVHDC 

PMERRINVDRIVERNAME 

PMERRINVLOGICALADDRESS 

Remarks 

A device context is a means of writing to a particular device. Before using GPI functions to cause 
output to be directed to the device context, the GpiAssociate function call must be issued (or the 
GPIA_ASSOC option specified on GpiCreatePS). 

DevOpenDC cannot be used to open a device context for a screen window; use WinOpenWindowDC 
instead. 

The device context is owned by the process from which DevOpenDC is issued. It cannot be accessed 
directly from any other process. If it still exists when the process terminates, it is automatically 
deleted by the system. When using a device context type of OD_METAFILE_NOQUERY the querying 
of attributes is not allowed. To improve performance of this type of metafile no error checking is 
performed to ensure that such API calls are not attempted. Query calls are accepted but the results 
returned are undefined. 

This function requires the existence of a message queue. 


An invalid type parameter was specified with 
DevOpenDC, or a function was issued that is invalid for a 
OD_METAFILE_NOQUERY device context. 

An invalid length or count parameter was specified. 

An invalid data parameter was specified with 
DevOpenDC. 

An invalid device-context handle or (micro presentation 
space) presentation-space handle was specified. 

A driver name was specified which has not been 
installed. 

An invalid device logical address was specified. 
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DevOpenDC - 
Open Device Context 


Related Functions 

Prerequisite Functions 

• Winlnitialize 

Other Related Functions 

• DevCIoseDC 

• GpiAssociate(for the output of GPI data) 

• PrfQueryProfileString 

• WinOpenWindowDC 

• WinQueryWindow 

Example Code 

This example calls DevOpenDC to create a memory device context with screen compatibility and 
then associates that context with a newly created presentation space. 

Idefine INCL_DEV /* Device Function definitions */ 


Idefine INCL_GPICONTROL /* GPI control Functions */ 

linclude <os2.h> 

HDC hdc; /* Device-context handle */ 

HAB hab ; /* Anchor-block handle */ 

/* context data structure */ 

DEVOPENSTRUC dop = {NULL, "DISPLAY", NULL, NULL, NULL, NULL, 

NULL, NULL, NULL}; 

HPS hps; /* presentation-space handle */ 

SIZEL sizl={0, 0}; /* use same page size as device */ 


/* create memory device context */ 

hdc = DevOpenDC(hab, 0D_M EMORY, "*", 5L, ( PDE VOPENDATA) &dop , NULLHANDLE); 

/* create a presentation space associated with the context */ 
hps = GpiCreatePS(hab, hdc, &sizl, GPIA_ASSOC | PU_PELS); 
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DevPostDeviceModes 
Post Device Modes 


#define INCL_DEV /* Or use INCL_PM */ 


LONG DevPostDeviceModes (HAB hab, PDRIVDATA pdrlvDrlverData, PSZ pszDrlverName, 

PSZ pszDeviceName, PSZ pszName, ULONG flOptions) 


This function returns, and optionally sets job properties. 


Parameters 

hab (HAB) - input 

Anchor-block handle. 

pdrlvDriverData (PDRIVDATA) - input/output 
Driver data. 

A data area that, on return, contains device data defined by the presentation driver. If the 
pointer to the area is NULL, this function returns the required size of the data area. 

The format of the data is the same as that which occurs within the DEVOPENSTRUC structure, 
passed on the pdopData parameter of DevOpenDC. 

pszDriverName (PSZ) - input 

Device-driver name. A string containing the name of the presentation driver; for example, 
“LASERJET." 

pszDeviceName (PSZ) - input 
Device-type name. 

Null-terminated string in a 32-byte field, identifying the device type; for example, "HP LaserJet 
IID” (model number). Valid names are defined by device drivers. 

Note: This parameter always overrides the data in the szDeviceNamel32 ] field of the 
DRIVDATA structure, passed in the pdrivDriverData parameter. 

pszName (PSZ) - input 
Device name. 

A name that identifies the device; for example, “PRINTER1.” If DPDMPOSTJOBPROP is 
specified in the flOptions parameter, the pszName parameter can be NULL. 

flOptions (ULONG) - input 
Dialog options. 

Options that control whether a dialog is displayed. 

DPDM_POSTJOBPROP 

This function allows the user to set properties for the print job by displaying a dialog 
and returning the updated job properties. Examples of job properties are paper 
size, paper orientation, and single-sided or duplex. 

The printer is configured in the shell using a dialog provided by the presentation 
driver. The configuration describes the actual printer setup such as number of paper 
bins, available paper sizes, and any installed hardware fonts. 

Before the job properties dialog is displayed the presentation driver merges any 
changes in the printer configuration with the data passed in the pdrivDriverData 
parameter. This allows, for example new paper sizes to be added into the job 
properties dialog. The parameter pszName can be specified as NULL although this 
is not recommended because the presentation driver cannot easily find the printer 
configuration to merge. 
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Post Device Modes 


It is the responsibility of the application to retrieve and store job properties. An 
application can choose to store job properties either on a per document or per 
application basis. The job properties can then be passed into DevOpenDC. Initial 
(default) job properties can be retrieved using DPDM_QUERYJOBPROP option. 

The application cannot tell if the user modified the job properties or just cancelled 
the dialog. Hence the job properties returned in the pdrivDriverData parameter must 
always be stored. 

The shell allows users to specify default job properties for a printer. The spooler 
API SpIQueryQueue can be used to retrieve these defaults. The spooler 
automatically adds the default job properties for a printer to any jobs that are 
submitted without job properties. 

DPDM_QUERYJOBPROP 

Do not display a dialog. Return the default job properties. These defaults are 
derived from the defaults for the chosen device; for example, “HP Laserjet IID” and 
the printer setup specified via the shell printer driver configuration dialog. 


Returns 

Size/error indicator. 

Value depends on what was passed as the pointer to pdrivDriverData: 

NULL 

DPDM_ERROR Error 
DPDM_NONE No settable options 
>0 Size in bytes required for pdrivDriverData. 

Other 

DPDM_ERROR Error 
DPDM_NONE No settable options 
DEV_OK OK. 

Possible returns from WinGetLastError 

PMERRINVDRIVERDATA 
PMERRDRIVERNOTFOUND 

PMERRINVDEVICENAME 

PMERRINVLOGICALADDRESS 

Remarks 

An application can first call this function with a NULL data pointer to find out how much storage is 
needed for the data area. Having allocated the storage, the application can then make the call a 
second time for the data to be entered. The returned data can then be passed in DevOpenDC as 
pdrivDriverData within the pdopData parameter. 

Calling this function requires the existence of a message queue. 

Use SplEnumDevice or SplEnumPrinter with fIT ype set to SPL_PR_DIRECT_DEVICE or 
SPL_PR_QUEUED_DEVICE to get a list of all the devices. 

To get information about a specific device use SpIQueryDevice. 


Invalid driver data was specified. 

The device driver specified with DevPostDeviceModes 
was not found. 

An invalid devicename parameter was specified with 
DevPostDeviceModes. 

An invalid device logical address was specified. 
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Post Device Modes 

Related Functions 

• DevOpenDC 


Example Code 

This example shows how to call DevPostDeviceModes and allocate a new buffer, if necessary, for the 
larger job properties (DRIVDATA structure). 

Idefine INCL_DEV 
Idefine INCL_D0S 
linclude <os2.h> 
linclude <memory.h> 

{ 

ULONG devrc=FALSE; 

HAB hab; 

PSZ pszPrinter; 

HDC hdc=NULL; 

PDRIVDATA pOldDri vData; 

PDRIVDATA pNewDri vData=NULL ; 

PDEVOPENSTRUC dops; 

LONG buflen; 


/* check size of buffer required for job properties */ 
buflen = DevPostDeviceModes ( hab, 

NULL, 

dops->pszDri verName, 
dops->pdri v->szDevi ceName , 
pszPrinter, 
DPDM_P0STJ0BPR0P 

); 


/* return error to caller */ 
if (buflen<=0) 

return (buflen) ; 

/* allocate some memory for larger job properties and */ 

/* return error to caller */ 

if (buflen != dops->pdri v->cb) 

{ 

i f (DosAl 1 ocMem ( ( PPVOID) SpNewDri vData ,buf 1 en , f ALLOC) ) 
return(DPDM_ERROR) ; 

} 

/* copy over old data so driver can use old job */ 

/* properties as base for job properties dialog */ 
pOldDrivData = dops->pdri v; 
dops->pdriv = pNewDri vData; 

memcpy( (PSZ) pNewDri vData, (PSZ) pOldDri vData, pOldDri vData->cb ); 

/* display job properties dialog and get updated */ 

/* job properties from driver */ 

devrc = DevPostDeviceModes ( hab, 

dops->pdri v, 
dops->pszDri verName , 
dops ->pdr i v->szDevi ceName , 
pszPrinter, 

DPDM POSTJOBPROP 

); 

return(devrc) ; 

} 
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Query Device Capabilities 


#define INCL_DEV /* Or use INCL_PM. Also in COMMON section */ 


BOOL DevQueryCaps (HDC hdc, LONG IStart, LONG ICount, PLONG alArray) 


This function queries the device characteristics. 

Parameters 

hdc (HOC) - input 

Device-context handle. 

IStart (LONG) - input 

First item of information. 

The number of the first item of information to be returned in alArray, counting from zero. 

ICount (LONG) - input 

Count of items of information. 

This is the count to be returned in alArray. It must be greater than zero. 

alArray (PLONG) - output 
Device capabilities. 

Array of ICount elements, starting with IStart. The array elements are numbered consecutively, 
starting with CAPS_FAMILY. The element number constants start with 0. See the appropriate 
bindings reference. 

If IStart + ICount —1 exceeds the current highest-defined element number, elements beyond the 
highest are returned as 0. 

CAPS_FAMILY Device type (values as for IType in DevOpenDC). 

CAPS_IO_CAPS Device input/output capability: 

CAPSIODUMMY 

Dummy device 
CAPS_SUPPORTS_OP 

Device supports output 
CAPS_SUPPORTS_IP 

Device supports input 
CAPS_SUPPORTS_IO 

Device supports output and input. 

CAPS_TECHNOLOGY Technology: 

CAPS_TECH_UNKNOWN 

Unknown 

CAPS_TECH_VECTOR_PLOTTER 

Vector plotter 

CAPS_TECH_RASTER_DISPLAY 

Raster display 

CAPS_TECH_RASTER_PRINTER 

Raster printer 

CAPS_TECH_RASTER_CAMERA 

Raster camera 

CAPS_TECH_POSTSCRIPT 

PostScript device. 
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Query Device Capabilities 


CAPS_DRIVER_VERSION 


CAPS_WIDTH 

CAPSHEIGHT 


CAPS_WIDTH_IN_CHARS 

CAPSHEIGHTINCHARS 

CAPSHORIZONT ALRESOLUTION 

CAPSVERTICALRESOLUTION 

CAPS_CHAR_WIDTH 

CAPS_CHAR_HEIGHT 

CAPS_SMALL_CHAR_WIDTH 

CAPSSMALLCHARHEIGHT 

CAPSCOLORS 


CAPSCOLORPLANES 

CAPS_COLOR_BITCOUNT 

CAPS_COLOR_TABLE_SUPPORT 


CAPS_MOUSE_BUTTONS 


Version identifier of the presentation driver. 

The high order word of the version identifier is 0. The 
low order word identifies the release, for example 
0x0120 is release 1.2. 

Media width (for a full screen, maximized window for 
displays) in pels. 

Media depth (for a full screen, maximized window for 
displays) in pels. (For a plotter, a pel is defined as the 
smallest possible displacement of the pen and can be 
smaller than a pen width.) 

Media width (for a full screen, maximized window for 
displays) in default character columns. 

Media depth (for a full screen, maximized window for 
displays) in default character rows. 

Horizontal resolution of device in pels per meter. 

Vertical resolution of device in pels per meter. 

Default character-box width in pels for VIO. 

Default character-box height in pels for VIO. 

Default small-character box width in pels for VIO. This 
is 0 if there is only one character-box size. 

Default small-character box height in pels for VIO. This 
is 0 if there is only one character-box size. 

Number of distinct colors supported at the same time, 
including reset (gray scales count as distinct colors). If 
loadable color tables are supported, this is the number 
of entries in the device color table. For plotters, the 
value returned is the number of pens plus one (for the 
background). 

Number of color planes. 

Number of adjacent color bits for each pel (within one 
plane). 

Loadable color table support: 

CAPS_COLT ABLRGB8 

1 if RGB color table can be loaded, with a 
minimum support of 8 bits each for red, 
green, and blue. 

CAPS_COLT ABL_RGB_8_PLUS 

1 if color table with other than 8 bits for 
each primary color can be loaded. 
CAPS_COLT ABL_TRUE_M IX 

1 if true mixing occurs when the logical 
color table has been realized, providing that 
the size of the logical color table is not 
greater than the number of distinct colors 
supported (see element CAPS_COLORS). 
CAPSCOLT ABLREALIZE 

1 if a loaded color table can be realized. 

The number of pointing device buttons that are 
available. A returned value of 0 indicates that there are 
no pointing device buttons available. 
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Query Device Capabilities 


CAPS_FOREGROUND_MIX_SUPPORT Foreground mix support: 

CAPS_FM_OR 

Logical OR. 

CAPSFMOVERPAINT 

Overpaint. 

CAPS_FM_XOR 

Logical XOR. 

CAPSFMLEAVEALONE 
Leave alone. 

CAPS_FM_AND 

Logical AND. 

CAPS_FM_GENERAL_BOOLEAN 

All other mix modes; see GpiSetMix. 

The value returned is the sum of the values appropriate 
to the mixes supported. A device capable of supporting 
OR must, as a minimum, return CAPS_FM_OR + 
CAPS_FM_OVERPAINT + CAPS_FM_LEAVEALONE, 
signifying support for the mandatory mixes OR, 
overpaint, and leave-alone. 

Note that these numbers correspond to the decimal 
representation of a bit string that is six bits long, with 
each bit set to 1 if the appropriate mode is supported. 

Those mixes returned as supported are guaranteed for 
all primitive types. For more information, see 
GpiSetMix. 

CAPS BACKGROUND MIX SUPPORT Background mix support: 

CAPS_BM_OR 

Logical OR. 

CAPS_BM_OVERPAINT 

Overpaint. 

CAPS_BM_XOR 

Logical XOR. 

CAPS_BM_LEAVEALONE 

Leave alone. 

CAPS_BM_AND 

Logical AND. 

CAPS_BM_GENERAL_BOOLEAN 

All other mix modes; see GpiSetBackMix. 

The value returned is the sum of the values appropriate 
to the mixes supported. A device must, as a minimum, 
return CAPS_BM_OVERPAINT + 
CAPS_BM_LEAVEALONE, signifying support for the 
mandatory background mixes overpaint, and 
leave-alone. 

Note that these numbers correspond to the decimal 
representation of a bit string that is four bits long, with 
each bit set to 1 if the appropriate mode is supported. 

Those mixes returned as supported are guaranteed for 
all primitive types. For more information, see 
GpiSetBackMix. 

CAPS_VIO_LOADABLE_FONTS Number of fonts that can be loaded for VIO. 
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Query Device Capabilities 


C APS_W I N DO W_B YTE_A LIG N M EN T 


CAPSBITMAPFORMATS 

CAPS_RASTER_CAPS 


CAPSMARKERHEIGHT 

CAPSMARKERWIDTH 

CAPS_DEVICE_FONTS 

CAPSGRAPHICSSUBSET 

CAPSGRAPHICSVERSION 

CAPS_GR APHICS_VECTOR_SU BSET 

CAPSDEVICEWINDOWING 


CAPSADDITIONALGRAPHICS 


Whether or not the client area of VIO windows should be 
byte-aligned: 

CAPS_BYTE_ALIGN_REQUIRED 

Must be byte-aligned. 
CAPS_BYTE_ALIGN_RECOMMENDED 

More efficient if byte-aligned, but not 
required. 

CAPS_BYTE_ALIGN_NOT_REQUIRED 

Does not matter whether byte-aligned. 

Number of bit-map formats supported by device. 
Capability for device raster operations: 

CAPS_RASTER_BITBLT 

1 if GpiBitBIt and GpiWCBitBIt supported 
CAPS_RASTER_BANDING 

1 if banding is supported 
CAPS_RASTER_BITBLT_SCALING 

1 if GpiBitBIt and GpiWCBitBIt with scaling 
supported. 

CAPS_RASTER_SET_PEL 

1 if GpiSetPel supported. 
CAPS_RASTER_FONTS 

1 if this device can draw raster fonts. 
CAPS_RASTER_FLOOD_FILL 

1 if GpiFloodFill is supported. 

Default marker-box height in pels. 

Default marker-box width in pels. 

Number of device-specific fonts. 

Graphics drawing subset supported. (3 indicates GOCA 
DR/3) 

Graphics architecture version number supported. (1 
indicates Version 1) 

Graphics vector drawing subset supported. (2 indicates 
GOCA VS/2) 

Device windowing support: 

CAPS_DEV_WINDOWING_SUPPORT 

1 if device supports windowing. 

Other bits are reserved 0. 

Additional graphics support: 

CAPS_GRAPHICS_KERNING_SUPPORT 

1 if device supports kerning. 
CAPS_FONT_OUTLINE_DEFAULT 

1 if device has a default outline font. 
CAPS_FONT_IMAGE_DEFAULT 

1 if device has a default image font. 
CAPS_SCALED_DEFAULT_MARKERS 

1 if default markers are to be scaled by the 
marker-box attribute. 
CAPS_COLOR_CURSOR_SUPPORT 

1 if device supports colored cursors. 
CAPS_PALETTE_MANAGER 

1 if device supports palette functions (see 
GpiCreatePalette). 
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Query Device Capabilities 


CAPS_PHYS_COLORS 

CAPSCOLORINDEX 

CAPS_GRAPHICS_CHAR_WIDTH 

CAPS_GRAPHICS_CHAR_HEIGHT 

CAPS_HORIZONTAL_FONT_RES 


CAPS_VERTICAL_FONT_RES 

CAPS_DEVICE_FONT_SIM 


CAPSLINEWIDTHTHICK 


CAPSCOSMETICWIDELINESUPPORT 

1 if device supports cosmetic thick lines 
(see GpiSetLineWidth). 

CAPS_ENHANCED TEXT 

1 if device supports full font file description 
and text alignment. 

Other bits are reserved 0. 

Maximum number of distinct colors available on the 
device. 

Maximum logical color-table index supported for this 
device. For the EGA and VGA drivers, the value is 63. 

Default graphics character-box width, in pels. 

Default graphics character-box height, in pels. 

Effective horizontal device resolution in pels per inch, 
for the purpose of selecting fonts. 

For printers, this is the actual device resolution, but for 
displays it may differ from the actual resolution for 
reasons of legibility. 

Effective vertical device resolution in pels per inch, for 
the purpose of selecting fonts. 

Identifies which simulations are valid on device fonts. 

Valid flags are: 

CAPS_DEVICE_FONT_SIM_BOLD 
CAPS_DE VICE_FONT_SI M_IT AL 1C 
CAPS_DEVICE_FONT_SIM_UNDERSCORE 
CAPS_DEVICE_FONT_SIM_STRIKEOUT 

Cosmetic thickness of lines and arcs on this device, 
when fxLineWidth is LINEWIDTH_THICK (see 
GpiSetLineWidth). The units are pels. A value of 0 is 
interpreted as 2 pels. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERR INV HDC An invalid device-context handle or (micro presentation 

space) presentation-space handle was specified. 

PMERR_INV_QUERY_ELEMENT_NO An invalid start parameter was specified with 

DevQueryCaps. 

PMERR_INV_LENGTH_OR_COUNT An invalid length or count parameter was specified. 
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Query Device Capabilities 

Remarks 

GpiQueryDevice can be used to find the handle of the currently associated device context. 


Related Functions 

Prerequisite Functions 

• DevOpenDC(for CAPS_FAMILY) 

Other Related Functions 

• DevQueryDeviceNames 

• DevQueryHardcopyCaps 

• GpiQueryDevice 

• GpiSetMix(for CAPS_FOREGROUND_MIX_SUPPORT) 

• GpiSetBackMix(for CAPS_BACKGROUND_MIX_SUPPORT) 


Example Code 

In this example the driver is queried to see if it supports input, output, or both. Note that a valid 
device context handle must be passed. This example assumes a DevOpenDC call has been made to 
obtain the device context handle. 

Idefine INCL_DEV 
linclude <0S2.H> 


HDC hdc; 

LONG 1 Start; 

LONG 1 Count; 

BOOL fl return; 

LONG al Array [CAPS ^TECHNOLOGY] ; 

1 Count = CAPS_TECHNOLOGY ; 

1 Start = CAPS_FAMILY; 

flreturn = DevQueryCaps(hdc, 

1 Start, 

1 Count, 
al Array) ; 


switch(al Array [CAPS_IO_CAPS] ) 


{ 

case CAPS_I0_SUPP0RTS_0P: 
break; 

case CAPS_IO_SUPPORTS_IP: 
break; 

case C APS_I0_SUPP0RTS_I0 : 

break; 

default: 

break; 

} 


/* device context handle */ 

/* number of first item */ 

/* count of items */ 

/* array of longs which */ 

/* will contain the return */ 
/* information. */ 

/* we test the CAPS_IO_CAPS */ 
/* element of the array to */ 
/* find out which options */ 
/* are supported. */ 

/* device supports output.*/ 


/* device supports input. */ 


/* device supports both */ 
/* input and output. */ 
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Query Device Names 


^define INCL_DEV /* Or use INCL_PM */ 


BOOL DevQueryDeviceNames (HAB hab, PSZ pszDriverName, PLONG pldn, 

PSTR32 aDeviceName, PSTR64 aDeviceDesc, PLONG pldt, 
PSTR16 aDataType) 


This function causes a presentation driver to return the names, descriptions, and data types of the 
devices it supports. 

Parameters 

hab (HAB) - input 

Anchor-block handle. 

pszDriverName (PSZ) - input 

Fully-qualified name of the file containing the presentation driver. 

The file-name extension is DRV. 
pldn (PLONG) - input/output 

Maximum number of device names and descriptions that can be returned. 
pldn can have the following values: 

Zero The number of device names and descriptions supported is returned; aDeviceName 
and aDeviceDesc are not updated. 

Nonzero pldn is updated to the number returned in aDeviceName and aDeviceDesc, 
aDeviceName and aDeviceDesc are updated. 

aDeviceName (PSTR32) - output 
Device-name array. 

An array of null-terminated strings, each element of which identifies a particular device. Valid 
names are defined by presentation drivers. 

aDeviceDesc (PSTR64) - output 
Device-description array. 

An array of null-terminated strings, each element of which is a description of a particular device. 
Valid descriptions are defined by presentation drivers. 

pldt (PLONG) - input/output 

Maximum number of data types that can be returned. 

pldt can have the following values: 

Zero The number of data types supported is returned, and aDataType is not updated. 

Nonzero pldt is updated to the number returned, and aDataType is updated. 

aDataType (PSTR1 6) - output 
Data type array. 

An array of null-terminated strings, each element of which identifies a data type. Valid data 
types are defined by presentation drivers. 
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Query Device Names 

Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRJNV_LENGTH_OR_COUNT An invalid length or count parameter was specified. 

Remarks 

An application can first call this function with pldn and pldt set to 0 to find how much storage is 
needed for the data areas. Having allocated the storage, the application calls the function a second 
time for the data to be entered. 

‘HP LaserJet" II’ is an example of a device name, ‘HP LaserJet II’ is an example of a device 
description, and ‘PM_Q_STD‘ is an example of a data type. 


Related Functions 

• DevQueryCaps 

• DevQueryHardcopyCaps 


Trademark of Hewlett-Packard Company 
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Example Code 

This example uses DevQueryDeviceNames to return the names, descriptions, and data types of 
supported devices for a presentation driver. The first call to DevQueryDeviceNames determines the 
number of names, description, and datatypes available; after allocating the arrays, the second call 
actually returns the information in the arrays. 

Idefine INCL_DEV /* Device Function definitions */ 

Idefine INCL_DOSMEMMGR /* DOS Memory Manager Functions */ 

linclude <os2.h> 


BOOL f Success; /* success indicator */ 
HAB hab; /* Anchor-block handle */ 
LONG pldn = OL; /* number of device names/descriptions */ 
LONG pldt = OL; /* number of data types */ 
PSTR32 aDeviceName; /* array of device names */ 
PSTR64 aDeviceDesc; /* array of device descriptions */ 
PSTR16 aDataType; /* array of data types */ 


/* query number of supported names/descriptions/data types 
(pldn & pldt both 0) */ 

fSuccess = DevQueryDeviceNames (hab, "IBM4201.DRV" , &pldn, 

aDeviceName, aDeviceDesc, &pldt, 
aDataType) ; 


if (fSuccess) 

{ 

/* allocate arrays */ 

DosAllocMem((VOID *)aDeviceName, (UL0NG)pldn*sizeof(STR32) , 
PAG_COMMIT | PAG_WRITE) ; 

DosAllocMem((VOID *)aDeviceDesc, (UL0NG)pldn*sizeof(STR64) , 
PAG_COMMIT | PAG_WRITE) ; 

DosAllocMem((VOID *)aDataType, (UL0NG)pldt*sizeof(STR16) , 
PAG_COMMIT | PAGJIRITE); 

/* query supported device information */ 

fSuccess = DevQueryDeviceNames(hab, "IBM4201.DRV", &pldn, 

aDeviceName, aDeviceDesc, &pldt, 
aDataType) ; 

} 
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Query Hardcopy Caps 


#define INCL_DEV /* Or use INCL_PM */ 


LONG DevQueryHardcopyCaps (HDC hdc, LONG IStartForm, LONG IForms, 

PHCINFO phciHclnfo) 


This function queries the hard-copy capabilities of a device. 

Parameters 

hdc (HDC) - input 

Device-context handle. 

IStartForm (LONG) - input 
Start-forms code. 

Forms-code number from which the query is to start. The first forms code has the value 0. 
IStartForm is used with IForms. 

IForms (LONG) - input 

Number of forms to query. 

If 0, the number of forms codes defined is returned. If greater than zero, this function returns the 
number of forms codes for which information is returned. 

For example, if there are five forms codes defined, and IStartForm = 2 and IForms = 3, a query 
is performed for forms codes 2, 3, and 4. The result is returned in the buffer pointed to by 
phciHclnfo. 

phciHclnfo (PHCINFO) - output 

Hard-copy capabilities information. 

A buffer containing the results of the query. The result consists of IForms copies of the HCINFO 
structure. 

At least one of the defined forms codes must have the HCAPS_CURRENT bit set. There might be 
more than one with either the HCAPS_CURRENT or the HCAPS_SELECTABLE bits set. 

For a job to be selected by the spooler for printing, each one of the forms specified in the FORM 
spooler parameter (see pszSpoolerParams in DEVOPENSTRUC) must be either 
HCAPS_CURRENT or HCAPS_SELECTABLE. The following are possibilities: 

• All forms specified are HCAPS_SELECTABLE. 

• The single form specified is HCAPS_CURRENT. 

• One of the forms is HCAPS_CURRENT, and all of the others are HCAPS_SELECTABLE. 


Returns 

Details of forms: 

DQHC_ERROR Error. 

>0 If IForms equals 0, number of forms available. 

If IForms does not equal 0, number of forms returned. 

Possible returns from WinGetLastError 

PMERR INV HDC An invalid device-context handle or (micro presentation 

space) presentation-space handle was specified. 

PMERR_INV_FORMS_CODE An invalid forms code parameter was specified with 

DevQueryHardcopyCaps. 

PMERR_INV_LENGTH_OR_COUNT An invalid length or count parameter was specified. 
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Query Hardcopy Caps 


Related Functions 

Prerequisite Functions 

• DevOpenDC 

Other Related Functions 

• DevQueryDeviceNames 

• DevQueryCaps 

Example Code 

The height and width of the capability of the output device is queried for each form code available. 
Note that a valid device context handle must be passed. This example assumes a DevOpenDC call 
has been made to obtain the device context handle of a printer. 

fdefine INCL_DEV 
linclude <0S2.H> 

HDC hdc; 

LONG IStartForm; /* Form code number from which the query */ 

/* is to start */ 

LONG 1 Forms; /* number of forms to query */ 

/* array of structures containing return information. */ 

HCINFO ahciHcInfo[5] ; 

LONG 1 return; 
int i ; 

HCINFO height [5]; 

HCINFO width [5]; 

IStartForm = OL; 

1 Forms = 0L; /* the actual number of forms codes is */ 

/* returned. There will be 1 return */ 

/* copies of the HINFO structure. */ 

1 return = DevQueryHardcopyCaps (hdc, 

IStartForm, 

1 Forms , 
ahciHclnfo) ; 

if (1 return > 5) 

{ 

1 return = 5L; /* we only want the first five form codes */ 

} /* if there are more than five */ 

for(i = 0; i < 1 return; i++) 

{ 

wi dth [1 return] .cx = ahciHcInfo[l return] .cx; 
hei ght [1 return] .cy = ahciHcInfo[l return] .cy; 

} 


Chapter 2. Device Functions 2-25 



2-26 PM Programming Reference 



Chapter 3. Direct Manipulation Functions 


This section describes functions that an application would use to initiate or participate in a direct 
manipulation operation. The following table shows all the direct manipulation (Drg) functions in 
alphabetic order. 


C Name 

C Name 

DrgAcceptDroppedFiles 

DrgQueryNativeRMF 

DrgAccessDraginfo 

DrgQueryNativeRMFLen 

DrgAddStrHandle 

DrgQueryStrName 

DrgAllocDraginfo 

DrgQueryStrNameLen 

DrgAllocDragtransfer 

DrgQueryT rueT ype 

DrgDeleteDraginfoStrHandles 

DrgQueryT rueTypeLen 

DrgDeleteStrHandle 

DrgReleasePS 

DrgDrag 

DrgSendT ransferMsg 

DrgDragFiles 

DrgSetDraglmage 

DrgFreeDraginfo 

DrgSetDragitem 

DrgFreeDragtransfer 

DrgSetDragPointer 

DrgGetPS 

DrgVerifyNativeRMF 

DrgPostT ransferMsg 

DrgVerifyRMF 

DrgPushDraginfo 

DrgVerifyTrueType 

DrgQueryDragitem 

DrgVerifyType 

DrgQueryDragitemCount 

DrgVerifyTypeSet 

DrgQueryDragitemPtr 



Chapter 3. Direct Manipulation Functions 


3-1 








































DrgAcceptDroppedFiles - 
Direct Manipulation for Files 


#define INCL_WINSTDDRAG 


BOOL DrgAcceptDroppedFiles (HWND Hwnd, PSZ pszPath, PSZ pszTypes, 

ULONG uiDefaultOp, ULONG uiReserved) 


This function handles the file direct manipulation protocol for a given window. 


Parameters 

Hwnd (HWND) - input 
Window handle. 

Handle of calling window. 

pszPath (PSZ) - input 
Directory. 

Directory in which to place the dropped files. If NULL, the files are placed in the current 
directory. 

pszTypes (PSZ) - input 
List of types. 

A list of types that are acceptable to the drop. This string is of the form: type[,type...]. 

When this pointer is NULL, any type of file will be accepted. 

uiDefaultOp (ULONG) - input 
Default drag operation. 

Default drag operation for this window. The operation is either DO_MOVE or DO_COPY. 

uiReserved (ULONG) - input 
Reserved. 


Returns 

Success indicator. 

TRUE Successful completion. 

FALSE Error occurred. 

Remarks 

This function handles the file direct manipulation protocol for a given window. The window responds 
(DOR_DROP, usDefaultOp) to DM DRAGOVER messages for items with a type matching the 
acceptable type string and with a rendering mechanism and format of <drm_os 2 file,drfjjnknown>. 

Not all dragged objects must match this criteria for the drop to be acceptable. 

After the drop occurs, this function handles the conversation required to complete the direct 
manipulation operation for all acceptable objects. A DM_ENDCONVERSATION (DMFL_TARGETFAIL) 
message is sent to the source when an object is unacceptable. 

When an error occurs during a move or copy, the caller is sent a DM_DRAGERROR message. The 
caller can take corrective action. 

As the move or copy operation is successful ly completed for each file, a DMDRAGFILECOMPLETE 
message is sent to the caller. No message is sent when the operation fails. 

The function returns TRUE if the operation is successful and FALSE if an error occurs. 
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DrgAcceptDroppedFiles - 
Direct Manipulation for Files 


Related Functions 

• DrgDragFiles 

Example Code 

This example uses the DrgAcceptDroppedFiles function to define the direct manipulation protocol of 
the given window, accept all file types, and use the current directory as the drop directory. 

Idefine INCL_WINSTDDRAG /* Direct Manipulation (Drag) Functions */ 
linclude <os2.h> 


BOOL fSuccess; /* Indicate success or failure */ 

HWND Hwnd; /* Handle of calling window */ 

PSZ pszPath; /* Directory in which to place the */ 

/* dropped files */ 

PSZ pszTypes; /* A list of types that are acceptable */ 

ULONG ulDefaultOp; /* Default drag operation */ 

pszPath = NULL; /* Drop file in current directory */ 

pszTypes = NULL; /* Accept any file type */ 

ulDefaultOp = D0_M0VE; /* Default drag operation is move */ 


fSuccess = DrgAcceptDroppedFiles (Hwnd, pszPath, pszTypes, 

ulDefaultOp, 0); 


Chapter 3. Direct Manipulation Functions 3-3 



DrgAccessDraginfo - 
Access Drag Information 


#define INCL_WINSTDDRAG 

BOOL DrgAccessDraginfo (PDRAGINFO pDraginfo) 

This function accesses a DRAGINFO structure. 

Parameters 

pDraginfo (PDRAGINFO) - input 
Pointer. 

Pointer to the DRAGINFO structure. 

Returns 

Success indicator. 

TRUE Successful completion. 

FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRACCESSDENIED The memory block was not allocated properly. 

Remarks 

This function is used by the target of a drag operation to access a DRAGINFO structure. The address 
of the structure is passed in a drag message (DM DRAGOVER, DM_DROP, or DM_DROPHELP). 

To release the structure, use the DrgFreeDraginfo function. 


Related Functions 

• DrgAllocDraginfo 

• DrgDrag 

• DrgFreeDraginfo 

• DrgPushDraginfo 

Example Code 

This example uses the DrgAccessDraginfo function to make an existing drag information structure 
(created by the DrgAllocDraginfo function) available. 

Idefine INCL_WINSTDDRAG /* Direct Manipulation (Drag) Functions */ 
linclude <os2.h> 

BOOL f Success; /* Indicate success or failure */ 

DRAGINFO Draginfo; /* Drag-information structure */ 

fSuccess = DrgAccessDraginfo(&Draginfo); 
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DrgAddStrHandle - 
Create String Handle 


#define INCL_WINSTDDRAG 


HSTR DrgAddStrHandle (PSZ pszStrlng) 


This function creates a handle to a string. 

Parameters 

pszStrlng (PSZ) - input 
String. 

String for which a handle is to be created. 


Returns 

String handle. 

NULLHANDLE Error occurred. 

Other String handle created. 


Possible returns from WinGetLastError 

PMERRINVALIDPARAMETERS An application parameter value is invalid for its converted 

PM type. For example: a 4-byte value outside the range 
—32,768 to +32,767 cannot be converted to a SHORT, and 
a negative number cannot be converted to a ULONG or 
USHORT. 

PMERR RESOURCE DEPLETION An internal resource depletion error has occurred. 


Remarks 

The handle can be used by any application to reference the input string. 

This function must be called by the source of a drag whenever a string is to be passed in a 
DRAGINFO structure. 


Related Functions 

• DrgDeleteStrHandle 

• DrgQueryStrName 
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DrgAddStrHandle - 
Create String Handle 


Example Code 

This example calls the DrgAddStrHandle function to create handles for strings that are used in a 
DRAGITEM structure. 

Idefine INCL_WINSTDDRAG /* Direct Manipulation (Drag) Functions */ 
linclude <os2.h> 


USHORT ID_ITEM = 1; 
HWND hwnd; 
DRAGITEM ditem; 


/* Drag item identifier 
/* Window handle 
/* DRAGITEM structure 


7 

7 

V 


/* Initialize the DRAGITEM structure */ 
ditem.hwndltem = hwnd; /* Conversation partner */ 

ditem.ulItemID = ID_ITEM; /* Identifies item being dragged */ 

ditem.hstrType = DrgAddStrHandle("DRT_TEXT") ; /* Item is text */ 

ditem. hstrRMF = DrgAddStrHandle(“<DRM_0S2FILE,DRF_TEXT>") ; 
ditem. hstrContainerName = DrgAddStrHandle("C:\\") ; 
ditem.hstrSourceName = DrgAddStrHandle("C:\\CONFIG.SYS") ; 
ditem. hstrTargetName = DrgAddStrHandle("C:\\0S2\\C0NFIG.SYS“) ; 
ditem.cxOffset = 0; /* X-offset of the origin of the */ 

image from the pointer hotspot*/ 
Y-offset of the origin of the */ 
image from the pointer hotspot*/ 
Source item control flags */ 


di tern. cyOff set = 0; 
ditem.fsControl = 0; 


/* 

/* 

/* 

/* 

/* 


object is open 


7 


ditem.fsSupportedOps = 0; 
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DrgAllocDraginfo - 
Allocate DRAGINFO Structure 


#define INCL_WINSTDDRAG 


PORAGINFO DrgAllocDraginfo (ULONG cDitem) 


This function allocates a DRAGINFO structure. 

Parameters 

cDitem (ULONG) - input 
Number of objects. 

Number of objects being dragged. This number must be greater than 0. 


Returns 

Pointer. 

Pointer to the DRAGINFO structure. 

NULL Error occurred. 

Other The DRAGINFO structure. 

Possible returns from WinGetLastError 

PMERRJNSUFFICIENT MEMORY The operation terminated through insufficient memory. 

PMERR_INVALID_PARAMETERS An application parameter value is invalid for its converted 

PM type. For example: a 4-byte value outside the range 
—32,768 to +32,767 cannot be converted to a SHORT, and 
a negative number cannot be converted to a ULONG or 
USHORT. 

Remarks 

This function must be called before the DrgDrag function is called. 

The caller can define a default operation for the objects represented by the DRAGINFO structure by 
modifying the usOperation field. If the usOperation field is modified, the new value will be sent to the 
target as the operation whenever a DO_DEFAULT operation would normally be sent. The caller 
should not modify any other part of the DRAGINFO structure. The DRAGITEM structures associated 
with the DRAGINFO structure should only be altered with DrgSetDragitem or by using a pointer 
obtained with DrgQueryDragitemPtr. 


Related Functions 

• DrgAccessDraginfo 

• DrgDrag 

• DrgFreeDraginfo 

• DrgPushDraginfo 
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DrgAllocDraginfo - 
Allocate DRAGINFO Structure 


Example Code 

This example calls the DrgAllocDraginfo function to create a Drag structure for a single object and 
uses the new structure to set the DRAGITEM (DrgSetDragitem) structure. 

Idefine INCL_WINSTDDRAG /* Direct Manipulation (Drag) Functions */ 
linclude <os2.h> 


PDRAGINFO pdinfo; /* Pointer to DRAGINFO structure */ 

HWND hwnd; /* Handle of calling (source) window */ 

BOOL flResult; /* Result indicator */ 

DRAGITEM ditem; /* DRAGITEM structure */ 

pdinfo = DrgAllocDraginfo(l); /* Create the DRAGINFO structure */ 

/* Set the drag item */ 


flResult= DrgSetDragitem(pdinfo, &ditem, (ULONG)sizeof(ditem) , 0); 
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DrgAllocDragtransfer - 
Allocate DRAGTRANSFER Structures 


#define INCL_WINSTDDRAG 


PDRAGTRANSFER DrgAllocDragtransfer (ULONG cdxfer) 


This function allocates a specified number of DRAGTRANSFER structures from a single segment. 

Parameters 

cdxfer (ULONG) - input 
Number of structures. 

Number of DRAGTRANSFER structures to be allocated. This number must be greater than 0. 

Returns 

Pointer. 

Pointer to an array of DRAGTRANSFER structures. 

NULL Error occurred. 

Other The array of DRAGTRANSFER structures. 

Possible returns from WinGetLastError 

PMERRMEMORY ALLOCATION ERR An error occurred during memory management. 

PMERRJNSUFFICIENT MEMORY The operation terminated through insufficient memory. 

PMERR_PARAMETER_OUT_OF_RANGE The value of a parameter was not within the defined valid 

range for that parameter. 

Remarks 

This function must be called before sending a DM_RENDER message. 

Related Functions 

• DrgFreeDragtransfer 

• DrgSendTransferMsg 

Example Code 

This example calls the DrgAllocDragtransfer function to allocate a single DRAGTRANSFER structure 
and adds a pointer to a DRAGITEM structure for an object that will be transferred. 

fdefine INCL_WINSTDDRAG /* Direct Manipulation (Drag) Functions*/ 
linclude <os2.h> 

PDRAGTRANSFER pResult; /* Pointer to DRAGTRANSFER structure */ 

PDRAGITEM pDragitem; /* Pointer to DRAGITEM structure */ 

pResult = DrgAllocDragtransfer(l); 

if (pResult != NULL) /* Indicate DRAGITEM to be transferred */ 
pResult->pditem = pDragitem; 
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DrgDeleteDraginfoStrHandles - 
Delete DRAGINFO String Handles 


#define INCL_WINSTDDRAG 


BOOL DrgDeleteDraginfoStrHandles (PDRAGINFO pDraglnfo) 


This function deletes each unique string handle in a DRAGINFO structure. 

Parameters 

pDraglnfo (PDRAGINFO) - input 
Pointer. 

Pointer to the DRAGINFO structure that contains string handles to delete. 

Returns 

Success indicator. 

TRUE Successful completion. 

FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERR INVALID PARAMETERS An application parameter value is invalid for its converted 

PM type. For example: a 4-byte value outside the range 
—32,768 to +32,767 cannot be converted to a SHORT, and 
a negative number cannot be converted to a ULONG or 
USHORT. 

Remarks 

Using this function is equivalent to calling the DrgDeleteStrHandle function for each unique string in 
a DRAGINFO structure. 

This function must be called by the target of a direct manipulation operation either: 

• After processing a DM_DROPHELP message 
or 

• After completing the direct manipulation operation begun as a result of a DM_DROP message. 


Related Functions 

• DrgDeleteStrHandle 

Example Code 

This example calls the DrgDeleteDraginfoStrHandles function to delete all unique string handles 
associated with the specified DRAGINFO structure (previously allocated by the DrgAllocDraginfo 
function). 

Idefine INCL_WINSTDDRAG /* Direct Manipulation (Drag) Functions */ 
linclude <os2.h> 

BOOL f Success; /* Indicate success or failure */ 

DRAGINFO Draginfo; /* DRAGINFO structure containing string */ 

/* handles to delete */ 

fSuccess = DrgDeleteDraginfoStrHandles (&Draginfo); 
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DrgDeleteStrHandle - 
Delete String Handle 


#define INCL_WINSTDDRAG 


BOOL DrgDeleteStrHandle (HSTR Hstr) 


This function deletes a string handle. 

Parameters 

Hstr (HSTR) - input 
String handle. 

The string handle to delete. 

Returns 

Success indicator. 

TRUE Successful completion. 

FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRJNVALID PARAMETERS An application parameter value is invalid for its converted 

PM type. For example: a 4-byte value outside the range 
—32,768 to +32,767 cannot be converted to a SHORT, and 
a negative number cannot be converted to a ULONG or 
USHORT. 

Remarks 

This function must be used to delete a string handle created by the DrgAddStrHandle function. 

Related Functions 

• DrgAddStrHandle 

• DrgDeleteDraginfoStrHandles 

Example Code 

This example calls the DrgDeleteStrHandle function to delete an existing string handle (returned by a 
previous call to the DrgAddStrHandle function). 

Idefine INCL_WINSTDDRAG /* Direct Manipulation (Drag) Functions */ 
linclude <os2.h> 

BOOL fSuccess; /* Indicate success or failure */ 

HSTR Hstr; /* String handle */ 

fSuccess = DrgDeleteStrHandle (Hstr); 
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DrgDrag 

Drag 


#define INCL_WINSTDDRAG 


HWND DrgDrag (HWND hwndSource, PDRAGINFO pDraglnfo, PDRAGIMAGE pdlmg, 
ULONG cdimg, LONG vkTerminate, PVOID pReserved) 


This function performs a drag operation. 


Parameters 

hwndSource (HWND) - input 
Window handle. 

Handle of the window calling DrgDrag. This window is the source of the drag. 

pDraglnfo (PDRAGINFO) - input/output 
Pointer. 

Pointer to the DRAGINFO structure. 

pdlmg (PDRAGIMAGE) - input 
Pointer. 

Pointer to an array of DRAGIMAGE structures. These structures describe the images that are to 
be drawn under the pointing device pointer during the drag. 

cdimg (ULONG) - input 
Array size. 

Size of the pdimg array. 

vkTerminate (LONG) - input 
Pointing device button. 

Pointing device button that ends the drag operation. 

VK_BUTTON1 Release of button 1 ends the drag. 

VK_BUTTON2 Release of button 2 ends the drag. 

VK_BUTTON3 Release of button 3 ends the drag. 

VK_ENDDRAG Release of the system-defined direct manipulation button ends the drag. This is 
the recommended value if the DrgDrag function call is invoked in response to a 
WM_BEGINDRAG message. 

pReserved (PVOID) - input 
Reserved. 

Must be set to NULL by the caller. 


Returns 

Window handle. 

Handle of window on which the dragged objects were dropped. 

NULL Error occurred. 

Other Window handle. 

Possible returns from WinGetLastError 

PMERR INVALID HWND An invalid window handle was specified. 
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DrgDrag - 
Drag 

PMERR_INVALID_PARAMETERS An application parameter value is invalid for its converted 

PM type. For example: a 4-byte value outside the range 
—32,768 to +32,767 cannot be converted to a SHORT, and 
a negative number cannot be converted to a ULONG or 
USHORT. 

PMERR_INSUFFICIENT_MEMORY The operation terminated through insufficient memory. 

Remarks 

This function: 

• Initiates a direct manipulation operation 

• Uses the input image to provide visual feedback to the user 

• Notifies other windows as the dragged object passes over 

• Notifies the destination if the object is dropped. 

DrgDrag is called when the system-defined direct-manipulation button is pressed while the pointer is 
over a window and a pointing device movement follows. As the pointer moves over a potential 
target, a DM_DRAGOVER message is sent to the target. When the pointer moves from one target 
window to another, a DM_DRAGLEAVE message is sent to the former target. 

If the pointer is over a valid target when the direct-manipulation button is released, a DM_DROP 
message is sent to the target. 

Before the DM_DROP message is sent, the cxOffset and cyOffset fields are copied from the 
DRAGIMAGE structures to the corresponding fields in the DRAGITEM structures. The values from 
the first DRAGIMAGE are copied to the first DRAGITEM, from the second DRAGIMAGE to the second 
DRAGITEM, and so on. The target can use this information to place the images in the same spatial 
relationship after the drop. If there are more DRAGITEM structures than there are DRAGIMAGE 
structures, the cxOffset and cyOffset from the final DRAGIMAGE are placed in each of the remaining 
DRAGITEM structures. 

The caller can define a default operation for the objects represented by the DRAGINFO structure by 
modifying the usOperation field. If the usOperation field is modified, the new value will be sent to the 
target as the operation whenever a DO_DEFAULT operation would normally be sent. The caller 
should not modify any other part of the DRAGINFO structure. The DRAGITEM structures associated 
with the DRAGINFO structure should only be altered with DrgSetDragitem or by using a pointer 
obtained with DrgQueryDragitemPtr. 

The following keys are active during the drag operation: 

Esc The drag operation is canceled. 

FI A DM_DROPHELP message is posted to the target so that it can provide context help for 

the drag operation. The drag operation is canceled. 

Before invoking DrgDrag, the caller is responsible for: 

• Obtaining a DRAGINFO structure using DrgAllocDraginfo 

• Initializing the DRAGITEM structures using DrgSetDragitem. 

On return from DrgDrag, the caller must free the structure using DrgFreeDraginfo. 

If the dragged objects are not dropped, NULL is returned. 
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DrgDrag 

Drag 


Related Functions 

Prerequisite Functions 

• DrgAllocDraginfo 

Other Related Functions 

• DrgFreeDraginfo 

• DrgSetDragitem 


Example Code 

This example uses the DrgDrag function to drag a single object in response to the 
direct-manipulation button being pressed while the pointer is over a drag object. The example 
shows the initialization of the DRAGITEM, DRAGINFO, and DRAGIMAGE structures used by the 
DrgDrag function. 


Idefine INCL_WINSTDDRAG /* Direct Manipulation (Drag) Functions */ 
Idefine INC L_W ININ PUT /* Window Input Functions */ 
linclude <os2.h> 


PDRAGINFO pdinfo; 
HWND hwnd; 

BOOL fl Result; 
DRAGITEM ditem; 
DRAGIMAGE dimg; 
HBITMAP hbm; 

HWND hwndDrop; 


/* Pointer to DRAGINFO structure */ 
/* Handle of calling (source) window */ 
/* Result indicator */ 
/* DRAGITEM structure */ 
/* DRAGIMAGE structure */ 
/* Bit-map handle */ 
/* Handle of drop (target) window */ 


case WM BEGINDRAG: 


/************************************************************* / 


/* Initialize the DRAGITEM structure 

/ 


******************************************************** } 


ditem. 

ditem. 

ditem. 

ditem. 

ditem. 

ditem, 

ditem, 

ditem. 


hwndltem = hwnd; /* Conversation partner */ 

ulItemID = ID_ITEM; /* Identifies item being dragged*/ 

hstrType = DrgAddStrHandle("DRT_TEXT") ; /* Text item */ 
hstrRMF = DrgAddStrHandle("<DRM_0S2FILE,DRF_TEXT>") ; 
hstrContainerName = DrgAddStrHandle("C:\\") ; 
hstrSourceName = DrgAddStrHandle("C:\\CONFIG.SYS") ; 
hstrTargetName = DrgAddStrHandle("C:\\0S2\\C0NFIG.SYS") ; 


cxOffset = 0; 


ditem.cyOffset = 0; 

ditem.fsControl = 0; 
ditem.fsSupportedOps = 0; 


/* X-offset of the origin of */ 
/* the image from the pointer */ 
/* hotspot */ 
/* Y-offset of the origin of */ 
/* the image from the pointer */ 
/* hotspot */ 
/* Source item control flags */ 
/* object is open */ 


I ************************************************************* j 

/* Create the DRAGINFO structure */ 

j ************************************************************* J 

pdinfo = DrgAllocDraginfo(l); 

if (Ipdinfo) return (FALSE); /* If allocation fails, */ 

/* return FALSE */ 


j ***************************************************** ******** j 

/* Initialize the DRAGIMAGE structure */ 

j-k ************************************************************ J 

dimg.cb = si zeof (DRAGIMAGE) ; /* Size control block */ 

dimg.cptl = 0; 

dimg.hlmage = hbm; /* Image handle passed to */ 
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DrgDrag - 
Drag 


dimg.sizlStretch.cx = 20L; 
dimg.sizlStretch.cy = 20L; 
dimg.fl = DRG_BITMAP | 
DRG_STRETCH ; 

dimg.cxOffset = 0; 
dimg.cyOffset = 0; 


/* DrgDrag */ 
/* Size to stretch ico or bmp to*/ 

/* Flags passed to DrgDrag */ 
/* Stretch to size specified */ 
/* in sizl Stretch */ 
/* Offset of the origin of */ 
/* the image from the pointer */ 
/* hotspot */ 


y************************************************************* y 
/* Set the drag item */ 

^************************************************************* y 

flResult= DrgSetDragitem(pdinfo, &ditem, (ULONG)sizeof(ditem) , 

0 ); 


j ************************************************************* / 

/* Perform the drag operation: */ 

/* - Give the user a visual cue by changing the pointer to a */ 

/* bit map */ 

/* - Send DM_DRAGOVER messages to the target window (in this */ 

/* case it is also the source) */ 

/************************************************************* / 
hwndDrop = DrgDrag (hwnd, /* Source of the drag */ 

pdinfo, /* Pointer to DRAGINFO structure */ 

(PDRAGIMAGE)&dimg, /* Drag image */ 

1, /* Size of the pdimg array */ 

VK_ENDDRAG, /* Release of direct-manipulation */ 

/* button ends the drag */ 

NULL); /* Reserved */ 
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DrgDragFiles - 
Begin Dragging Files 


#define INCL_WINSTDDRAG 


BOOL DrgDragFiles (HWND Hwnd, PAPSZ pFIles, PAPSZ pTypes, PAPSZ pTargets, 
ULONG cFlles, HPOINTER hptrDrag, ULONG vkTermlnate, 
BOOL ISourceRender, ULONG ulReserved) 


This function begins a direct manipulation operation for one or more files. 


Parameters 

Hwnd (HWND) - input 
Window handle. 

Handle of calling window. 

pFIles (PAPSZ) - input 
File names. 

The names of the files to be dragged. 

pTypes (PAPSZ) - input 
File types. 

The file types of the files to be dragged. 

pTargets (PAPSZ) - input 
Target file names. 

cFlles (ULONG) - input 
Number of files. 

Number of files to be dragged. 

hptrDrag (HPOINTER) - input 
Icon. 

Icon to display during the drag. 

vkTermlnate (ULONG) - input 
Button. 

Button that ends the drag. 

fSourceRender (BOOL) - input 
Flag. 

Flag to indicate whether the source must perform the move or copy. 

TRUE The caller will receive a DM_RENDERFILE message for each file. 

FALSE All file manipulation is performed by DrgDragFiles. 

ulReserved (ULONG) - input 
Reserved. 


Returns 

Success indicator. 

TRUE The drag operation was initiated successfully. 
FALSE An error occurred. 
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DrgDragFiles - 
Begin Dragging Files 


Remarks 

This function begins a direct manipulation operation for one or more files. DRAGINFO and 
DRAGITEM structures are allocated and initialized, and are then used as input to DrgDrag. All of the 
post-drag conversation required to complete the direct manipulation operation is handled by an 
object window created by this function. 

The caller should set fSourceRender to TRUE if it must perform the file manipulation for any of these 
files. When fSourceRender is TRUE, the caller receives a DM_RENDERFILE message as the 
drag-object window receives a DM RENDER message. The caller should move or copy the file after 
receiving the DM_RENDERFILE message. The caller should then send a DM_FILERENDERED 
message to the drag-object window, and the drag-object window should send a 
DMRENDERCOMPLETE message to the target. 

When pTypes is NULL, the .TYPE EA is interrogated to determine the type for each file in pFiles. 

When pTypes is not NULL, the size of the array is expected to be the same as the size of pFiles. 

When any individual pointer in the array is NULL, the .TYPE EA for the corresponding file is read. 
When .TYPE EA does not exist for any file for which it is needed, a type of DRTJJNKNOWN is used. 

When pTargets is NULL, the target name for a file will be the same as the source file name with the 
path information removed. If pTargets is not NULL, the size of the array is expected to be the same 
as the size of pFiles. If any individual pointer in the array is NULL, the target name for the 
corresponding file will match the source name minus the path information. 

The rendering mechanism and format for each file is: <drm_os2File,drfunknown>. 

When an error occurs during the move or copy, the caller is sent a DM_DRAGERROR message. The 
caller can take corrective action. 

As the operation is complete for each file in the list, a DMDRAGFILECOMPLETE message is sent to 
the caller of DrgDragFiles. The caller is thus notified that resources can be freed for a particular file. 

This function returns TRUE if the drag operation was initiated successfully and FALSE if an error 
occurred. 

Related Functions 

• DrgAcceptDroppedFiles 
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DrgDragFiles - 
Begin Dragging Files 


Example Code 

This example calls the DrgDragFiles function to begin direct manipulation for a single file object, 
using the same source and target name, and determining the file type based on the file’s type EA. 

Idefine INCL_WINSTDDRAG /* Direct Manipulation (Drag) Functions */ 

Idefine INCL_WININPUT /* Window Input Functions */ 

linclude <os2.h> 

BOOL fSuccess; /* Indicate success or failure */ 

HWND Hwnd; /* Handle of calling window */ 

PSZ pFi 1 es [1] ; /* The names of the files to be dragged */ 

PSZ pTypes[l]; /* The file types of the files to be */ 

/* dragged */ 

PSZ pTargets[l]; /* The target file names */ 

HPOINTER hptrDrag; /* Icon to display during drag */ 

pFi 1 es [0] = "FILENAME. EXT"; /* Copy file name to string array */ 
pTargets[0] = NULL; /* Use source name as target name */ 

pTypes[0] = NULL; /* Query type EA to determine file type */ 

fSuccess = DrgDragFiles (Hwnd, pFiles, pTypes, pTargets, 1, 
hptrDrag, VK_BUTT0N2, FALSE, 0L); 
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DrgFreeDraginfo - 
Free DRAGINFO Structure 


#define INCLWINSTDDRAG 


BOOL DrgFreeDraginfo (PDRAGINFO pDraginfo) 


This function frees a DRAGINFO structure allocated by DrgAllocDraginfo. 

Parameters 

pDraginfo (PDRAGINFO) - input 
Pointer. 

Pointer to the DRAGINFO structure. 

Returns 

Success indicator. 

TRUE Successful completion. 

FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRMEMORY DEALLOCATION ERR An error occurred during memory management. 

PMERR_SOURCE_SAME_AS_T ARGET The direct manipulation source and target process are 

the same. 

Remarks 

DrgFreeDraginfo fails with an error of PMERR_SOURCE_SAME_AS_TARGET if it is called by the 
process that called DrgDrag before DrgDrag returns. When a process is performing a drag operation 
between two of its own windows, this prevents the source window from freeing the DRAGINFO 
structure before the target window finishes processing. 


Related Functions 

Prerequisite Functions 

• DrgAllocDraginfo 

Other Related Functions 

• DrgDrag 

• DrgAccessD rag info 

• DrgPushDraginfo 
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DrgFreeDraginfo - 
Free DRAGINFO Structure 


Example Code 

This example calls the DrgFreeDraginfo function to free an existing DRAGINFO structure allocated by 
the DrgAllocDraginfo function after a drag operation has completed. 

Idefine INCL_WINSTDDRAG /* Direct Manipulation (Drag) Functions */ 
linclude <os2.h> 


BOOL f Success; /* Indicate success or failure */ 

PDRAGINFO pdinfo; /* Pointer to DRAGINFO structure */ 

HWND hwnd; /* Handle of calling (source) window */ 

DRAGIMAGE dimg; /* DRAG I MAGE structure */ 

HWND hwndDrop; /* Handle of drop (target) window */ 

j **************************************************************** j 

/* Perform the drag operation: */ 

/* - Give the user a visual cue by changing the pointer to a */ 

/* bit map */ 

/* - Send DM DRAGOVER messages to the target window (in this */ 

/* case it is also the source) */ 

j-klclc ************************************************************* j 

hwndDrop = DrgDrag(hwnd, /* Source of the drag */ 

pdinfo, /* Pointer to DRAGINFO structure */ 

(PDRAGIMAGE)&dimg, /* Drag image */ 

1, /* Size of the pdimg array */ 

VK_ENDDRAG, /* Release of drag button */ 

/* Terminates the drag */ 

NULL); /* Reserved */ 


f Success = DrgFreeDraginfo (&pdinfo) ; 
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DrgFreeDragtransfer - 
Free DRAGTRANSFER Storage 


#define INCL_WINSTDDRAG 


BOOL DrgFreeDragtransfer (PDRAGTRANSFER pdxfer) 


This function frees the storage associated with a DRAGTRANSFER structure. 

Parameters 

pdxfer (PDRAGTRANSFER) - input 
Pointer. 

Pointer to the DRAGTRANSFER structures to be freed. 

Returns 

Return code. 

0 The structure was freed. 

Other Deallocation failed. 

Possible returns from WinGetLastError 

PMERRMEMORYDEALLOCATIONERR An error occurred during memory management. 

Remarks 

This function frees the DRAGTRANSFER structures allocated by calls to DrgAllocDragtransfer. When 
all of the DRAGTRANSFER structures have been freed, the memory block containing the 
DRAGTRANSFER array is deallocated. 

Related Functions 

• DrgAllocDragtransfer 

Example Code 

This example calls the DrgFreeDragtransfer function to free an existing DRAGTRANSFER structure 
allocated by the DrgAllocDragtransfer function. 

Idefine INCL_WINSTDDRAG /* Direct Manipulation (Drag) Functions */ 
linclude <os2.h> 

BOOL f Success; /* Indicate success or failure */ 

DRAGTRANSFER dxfer; /* Pointer to DRAGTRANSFER structure */ 

fSuccess = DrgFreeDragtransfer(&dxfer) ; 
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DrgGetPS - 

Get Drag Presentation Space 


#define INCL_WINSTDDRAG 


HPS DrgGetPS (HWND Hwnd) 


This function gets a presentation space that is used to provide target feedback to the user during a 
drag operation. 

Parameters 

Hwnd (HWND) - input 
Window handle. 

Handle of the window for which presentation space is required. 

Returns 

Presentation-space handle. 

Presentation-space handle used for drawing in the window. 

NULLHANDLE Error occurred. 

Possible returns from WinGetLastError 

PMERRINVALIDHWND 
PMERRNOTDRAGGING 

Remarks 

This function returns a handle to a presentation space that can be used for drawing while a direct 
manipulation operation is in progress. 

DrgGetPS is called only during a direct manipulation operation. This function is called only after a 
DM_DRAGOVER, DM_DRAGLEAVE, or DM_DROP message has been received. 

In order to draw target emphasis, an application must use DrgGetPS and DrgReleasePS to unlock its 
window. 

The presentation space created with DrgGetPS must be freed with DrgReleasePS. 

Related Functions 

• DrgReleasePS 


An invalid window handle was specified. 

A drag operation is not in progress at this time. 
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DrgGetPS - 

Get Drag Presentation Space 


Example Code 

This example uses the DrgGetPS function to get a presentation space handle which is used during 
drag operations such as loading a drag bit map. When finished with the presentation space, release 
it with the DrgReleasePS function. 

Idefine INCL.WINSTDDRAG /* Direct Manipulation (Drag) Functions */ 
linclude <os2.h> 

HPS hps; /* Presentation space handle */ 

HWND hwnd; /* Handle of the window for which */ 

/* presentation space is required */ 

case DM_DRAGOVER: 

hps = DrgGetPS(hwnd) ; 

DrawTargetEmphasis(hps, hwnd); 

DrgReleasePS(hps) ; 
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DrgPostT ransferMsg 
Post Drag Message 


#define INCL_WINSTDDRAG 


BOOL DrgPostT ransferMsg (HWND hwndTo, ULONG ulMsgld, PDRAGTRANSFER pdxfer, 

ULONG fs, ULONG uiReserved, BOOL (Retry) 


This function posts a message to the other application involved in the direct manipulation operation. 

Parameters 

hwndTo (HWND) - input 
Window handle. 

Window handle to which the message is to be posted: 

Target hwndltem in the DRAGITEM structure. 

Source hwndClient in the DRAGTRANSFER structure. 

ulMsgld (ULONG) - input 
Message identifier. 

Identifier of the message to be posted. DM_RENDERCOMPLETE is the only valid message. 

pdxfer (PDRAGTRANSFER) - input 
Pointer. 

Pointer to the DRAGTRANSFER structure. 

fs (ULONG) - input 
Flags. 

The flags to be passed in the param2 parameter of the message. 

uiReserved (ULONG) - input 
Reserved. 

This must be 0. 

(Retry (BOOL) - input 
Retry indicator. 

TRUE If the destination queue is full, the message posting is retried at 1-second intervals 
until the message is posted successfully. 

In this case, DrgPostTransferMsg dispatches any messages in the queue by calling 
WinPeekMsg and WinDispatchMsg in a loop. The application can receive messages 
sent by other applications while it is trying to post drag transfer messages. 

FALSE The call returns FALSE without retrying. 

Returns 

Success indicator. 

TRUE Successful completion. 

FALSE Error occurred. 
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DrgPostTransferMsg - 
Post Drag Message 


Remarks 

The usReply field in the DRAGTRANSFER structure is set to 0 before the message is posted. If the 
posting fails for any reason, FALSE is returned. 


Related Functions 

• DrgSendTransferMsg 

Example Code 

This example calls the DrgPostTransferMsg function to respond to a DM_RENDER message from the 
target. The response consists of a DMRENDERCOMPLETE message, plus a flag indicating whether 
the render was successful (DMFL_RENDEROK) or not (DMFL_RENDERFAIL). 

Idefine INCL_WINSTDDRAG /* Direct Manipulation (Drag) Functions */ 
linclude <os2.h> 


MPARAM mpl; /* Message parameter 1 */ 

BOOL f Success; /* Indicate success or failure */ 

BOOL Rendered; /* Success of render operation */ 

PDRAGTRANSFER pdxfer; /* Pointer to DRAGTRANSFER structure */ 

case DM_RENDER: 

pdxfer = ( PDRAGTRANSFER) PVOIDFROMMP (mpl) ; /* Get DRAGTRANSFER */ 

/* structure */ 

J icicle *********** -kirk Irk Irk Irk irk 1c -kirk Irk irk Irk Irk 1c -kirk Irk Irk Irk *********** Irk j 

/* Attempt to render file */ 


Jit*** ********************************************************* j 

if (Rendered) 

{ 

fSuccess = DrgPostTransferMsg(pdxfer->pditem, 

DM_RENDERCOMPLETE, 

pdxfer, 

DMFL_RENDEROK, 

0, FALSE); 

return (MRESULT)TRUE; 

} 

else 

{ 

fSuccess = DrgPostTransferMsg(pdxfer->pditem, 

DM_RENDERCOMPLETE , 
pdxfer, 

DMFL_RENDERFAIL, 

0, FALSE); 

return (MRESULT)FALSE; 

} 
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DrgPushDraginfo - 
Access a DRAGINFO Structure 


#define INCL_WINSTDDRAG 


BOOL DrgPushDraginfo (PDRAGINFO pDraginfo, HWND hwndDest) 


This function gives a process access to a DRAGINFO structure. 


Parameters 

pDraginfo (PDRAGINFO) - input 
Pointer. 

Pointer to the DRAGINFO structure. 

hwndDest (HWND) - input 
Window handle. 

Handle of the window whose process is to be given access to a DRAGINFO structure. 


Returns 

Success indicator. 

TRUE Successful completion. 

FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRACCESSDENIED The memory block was not allocated properly. 

PMERR_INSUFFICIENT_MEMORY The operation terminated through insufficient memory. 

Remarks 

The receiving process is responsible for: 

1. Deleting the string handles in the DRAGINFO structure with DrgDeleteDraginfoStrHandles 

2. Freeing the DRAGINFO structure using DrgFreeDraginfo. 

Related Functions 

• DrgAllocDraginfo 

• DrgDrag 

• DrgAccessDraginfo 

• DrgFreeDraginfo 
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DrgPushDraginfo - 
Access a DRAGINFO Structure 


Example Code 

This example calls the DrgPushDraginfo function to grant access to a DRAGINFO structure to the 
process owning the specified window handle. The DRAGINFO structure was previously allocated 
using the DrgAllocDraginfo function. 

Idefine INCL_WINSTDDRAG /* Direct Manipulation (Drag) Functions */ 
linclude <os2.h> 

BOOL fSuccess; /* Indicate success or failure */ 

DRAGINFO Draginfo; /* Pointer to DRAGINFO structure */ 

HWND hwndDest; /* Handle of window whose process will */ 

/* will be given access to the DRAGINFO */ 

/* structure */ 

fSuccess = DrgPushDraginfo(&Draginfo, hwndDest) ; 


Chapter 3. Direct Manipulation Functions 3-27 



DrgQueryDragitem - 
Get DRAGITEM Structure 


#define INCL_WINSTDDRAG 


BOOL DrgQueryDragitem (PDRAGINFO pOraglnfo, ULONG cbBuffer, PDRAGITEM pDragltem, 

ULONG litem) 


This function returns a DRAGITEM structure used in the direct manipulation operation. 

Parameters 

pDraglnfo (PDRAGINFO) - input 
Pointer. 

Pointer to the DRAGINFO structure from which the DRAGITEM structure is obtained. 

cbBuffer (ULONG) - input 
Number of bytes. 

Maximum number of bytes to copy. 

pDragltem (PDRAGITEM) - output 
Pointer. 

Pointer to the buffer into which the DRAGITEM structure is copied. 

litem (ULONG) - input 
DRAGITEM index. 

Zero-based index of the DRAGITEM to be returned. 

Returns 

Success indicator. 

TRUE Successful completion. 

FALSE Error occurred. 

Remarks 

This function returns the DRAGITEM structure identified by iltem. 

Related Functions 

• DrgSetDragitem 

• DrgQueryDragitemPtr 
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DrgQueryDragitem - 
Get DRAGITEM Structure 


Example Code 

This example calls the DrgQueryDragitem function to return the entirety of the first DRAGITEM 
structure in the given DRAGINFO structure, after which it obtains the source window handle. 


Idefine INCL_WINSTDDRAG 

/* Direct Manipulation (Drag) Functions 

*/ 

linclude <os2.h> 



BOOL 

fSuccess; 

/* Indicate success or failure 

*/ 

DRAGINFO 

Draginfo; 

/* DRAGINFO structure from which the 

*/ 



/* DRAGITEM structure is obtained 

*/ 

ULONG 

cbBuffer; 

/* Maximum number of bytes to copy 

*/ 

DRAGITEM 

Dragitem; 

/* Buffer into which the DRAGITEM 

*/ 



/* structure is copied 

*/ 

ULONG 

i Item; 

/* Zero-based index of the DRAGITEM 

*/ 



/* to be returned 

*/ 

HWND 

hwndSource; 

/* Source window handle for the drag 

*/ 

cbBuffer 

= si zeof (DRAGITEM) ; /* Copy entire DRAGITEM structure 

*/ 

iltem = 0 

» 

/* Return first DRAGITEM 

*/ 


fSuccess = DrgQueryDragitem(&Draginfo, cbBuffer, &Dragitem,i Item) ; 


hwndSource = Dragitem.hwndltem; /* Obtain source window handle */ 
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DrgQueryDragitemCount - 
Get Dragged Object Count 


#define INCL_WINSTDDRAG 


ULONG DrgQueryDragitemCount (PDRAGINFO pDraglnfo) 


This function returns the number of objects being dragged during the current direct manipulation 
operation. 


Parameters 

pDraglnfo (PDRAGINFO) - input 
Pointer. 

Pointer to the DRAGINFO structure for which the number of dragged objects is requested. 


Returns 

Number of objects. 

Number of objects being dragged. 

Example Code 

This example calls the DrgQueryDragitemCount function to return the number of DRAGITEM 
structures in the corresponding DRAGINFO structure, which maps to the number of objects being 
dragged. 

Idefine INCL_WINSTDDRAG /* Direct Manipulation (Drag) Functions */ 
linclude <os2.h> 

ULONG cDitem; /* Number of objects being dragged */ 

DRAGINFO Draginfo; /* DRAGINFO structure queried for the */ 

/* number of drag objects */ 

cDitem = DrgQueryDragitemCount (&Draginfo) ; 
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DrgQueryDragitemPtr - 
Get Pointer to DRAGITEM Structure 


#define INCL_WINSTDDRAG 


PDRAGITEM DrgQueryDragitemPtr (PDRAGINFO pDraginfo, ULONG ullndex) 


This function returns a pointer to the DRAGITEM structure used in the direct manipulation operation. 


Parameters 

pDraginfo (PDRAGINFO) - input 
Pointer. 

Pointer to the DRAGINFO structure from which the DRAGITEM structure is obtained. 

ullndex (ULONG) - input 
DRAGITEM index. 

Zero-based index of the DRAGITEM structure for which the pointer is to be returned. 


Returns 

Pointer. 

Pointer to the DRAGITEM structure. 

Remarks 

This function returns a pointer to ulltemID in the DRAGITEM structure used in the direct manipulation 
operation. 

Related Functions 

• DrgQueryDragitem 

Example Code 

This example calls the DrgQueryDragitemPtr function to return a pointer to first DRAGITEM structure 
in the given DRAGINFO structure, after which it obtains the source window handle. 

Idefine INCL_WINSTDDRAG /* Direct Manipulation (Drag) Functions */ 
linclude <os2.h> 


PDRAGITEM pDragitem; /* DRAGITEM structure pointer */ 

DRAGINFO Draginfo; /* DRAGINFO structure from which the */ 

/* DRAGITEM structure is obtained */ 

ULONG ullndex; /* Zero-based index of the DRAGITEM */ 
/* structure pointer to be returned */ 
HWND hwndSource; /* Source window handle for the drag */ 

USHORT usn = 0; /* Return pointer to first DRAGITEM */ 


pDragitem = DrgQueryDragitemPtr(&Draginfo,usn) ; 

hwndSource = pDragitem->hwndItem; /* Obtain source window handle */ 
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DrgQueryNativeRMF - 
Get Format of a Dragged Object 


#define INCL_WINSTDDRAG 


BOOL DrgQueryNativeRMF (PDRAGITEM pOragltem, ULONG cbBuflen, PCHAR ppBuffer) 


This function obtains the ordered pair that represents the native rendering mechanism and format of 
the dragged object. 

Parameters 

pDragltem (PDRAGITEM) - input 
Pointer. 

Pointer to the DRAGITEM structure whose native rendering mechanism and format are to be 
obtained. 

cbBuflen (ULONG) - input 
Number of bytes. 

Maximum number of bytes to copy to the buffer. 

ppBuffer (PCHAR) - output 
Pointer. 

Pointer to the buffer in which the null-terminated string is to be returned. 


Returns 

Success indicator. 

TRUE Successful completion. 
FALSE Error occurred. 


Possible returns from WinGetLastError 

PMERR INVALID PARAMETERS An application parameter value is invalid for its converted 

PM type. For example: a 4-byte value outside the range 
—32,768 to +32,767 cannot be converted to a SHORT, and 
a negative number cannot be converted to a ULONG or 
USHORT. 


Remarks 

If the rendering mechanism and format string for the object are NULL, FALSE is returned. If TRUE is 
returned, the format of the string is: <mechanism,format>. 

The native rendering mechanism and format are the first ordered pair, or the first ordered pair 
produced by a cross product, in the string associated with hstrRMF in the DRAGITEM structure. 

DrgQueryNativeRMFLen can be used to determine the size of the buffer required to hold the string 
returned by this function. 


Related Functions 

Prerequisite Functions 

• DrgQueryNativeRMFLen 

Other Related Functions 

• DrgVerifyNativeRMF 
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DrgQueryNativeRMF - 
Get Format of a Dragged Object 


Example Code 

This example shows how to obtain the window handle of the source of a drag item. 

Idefine INCL_WINSTDDRAG /* Direct Manipulation (Drag) Functions */ 

Idefine INCL_DOSMEMMGR /* Memory Management Functions for */ 

/* DosSubAlloc */ 

linclude <0S2.H> 

DRAGITEM ditem; 

PVOID pMem; 

PSZ pszBuffer; 

ULONG cb; 

BOOL rc, fResult; 

cb = DrgQueryNativeRMFLen(&ditem) + 1; 

rc = DosSubAlloc(pMem, (PVOID *) pszBuffer, cb); 

if (!rc) 

{ 

fResult = DrgQueryNativeRMF(&ditem, cb, pszBuffer); 

} 
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DrgQueryNativeRMFLen - 

Get String Length for Native RMF of Dragged Object 


#define INCL_WINSTDDRAG 


ULONG DrgQueryNativeRMFLen (PDRAGITEM pDragitem) 


This function obtains the length of the string representing the native rendering mechanism and 
format of the dragged object. 


Parameters 

pDragitem (PDRAGITEM) - input 
Pointer. 

Pointer to the DRAGITEM structure whose native rendering mechanism and format string length 
are to be obtained. 

Returns 

String length. 

String length of the ordered pair: 

0 Error occurred. 

Other String length of the ordered pair, excluding the null-terminating byte. 

Possible returns from WinGetLastError 

PMERRINVALID PARAMETERS An application parameter value is invalid for its converted 

PM type. For example: a 4-byte value outside the range 
—32,768 to +32,767 cannot be converted to a SHORT, and 
a negative number cannot be converted to a ULONG or 
USHORT. 


Remarks 

This function is used to determine the size of the buffer that contains the string representing the 
native rendering mechanism and format of the dragged object. 

If the input string handle is NULLHANDLE or not valid, a length of 0 is returned. 


Related Functions 

• DrgQueryNativeRMF 
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DrgQueryNativeRMFLen - 
Get String Length for Native RMF of Dragged Object 

Example Code 

This example shows how to obtain the window handle of the source of a drag item. 


Idefine INCL_WINSTDDRAG /* Direct Manipulation (Drag) Functions */ 
Idefine INCL_DOSMEMMGR /* Memory Management Functions for */ 

/* DosSubAlloc */ 

linclude <0S2.H> 

DRAGITEM ditem; 

PVOID pMem; 

PSZ pszBuffer; 

ULONG cb; 

BOOL rc, fResult; 

cb = DrgQueryNativeRMFLen(&ditem) + 1; 

rc = DosSubAlloc(pMem, (PVOID *) pszBuffer, cb); 

if (!rc) 

{ 

fResult = DrgQueryNativeRMF(&ditem, cb, pszBuffer); 

} 
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DrgQueryStrName 
Get String Contents 


#define INCL_WINSTDDRAG 


ULONG DrgQueryStrName (HSTR Hstr, ULONG cbBuflen, PSZ pszBuffer) 


This function gets the contents of a string associated with a string handle. 


Parameters 

Hstr (HSTR) - input 
String handle. 

The handle must have been created with DrgAddStrHandle. 

cbBuflen (ULONG) - input 
Number of bytes. 

Maximum number of bytes to copy. 

pszBuffer (PSZ) - output 
Buffer. 

Buffer where the null-terminated string is returned. 


Returns 

Number of bytes. 

Number of bytes written to pszBuffer. 


Possible returns from WinGetLastError 

PMERR INVALID PARAMETERS An application parameter value is invalid for its converted 

PM type. For example: a 4-byte value outside the range 
—32,768 to +32,767 cannot be converted to a SHORT, and 
a negative number cannot be converted to a ULONG or 
USHORT. 


Remarks 

This function should be called whenever the contents of a string referenced by a drag string handle 
are required. If the input string handle is NULLHANDLE or not valid, a null string is returned. 


Related Functions 

Prerequisite Functions 

• DrgQueryStrNameLen 

Other Related Functions 

• DrgAddStrHandle 
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DrgQueryStrName - 
Get String Contents 


Example Code 

This example shows how to obtain the contents of a string given that the string handle is known. The 
string handle must have been originally created with the DrgAddStrHandle function. 

Idefine INCL_WINSTDDRAG /* Direct Manipulation (Drag) Functions */ 

Idefine INCL_DOSMEMMGR /* Memory Management Functions for */ 

/* DosAl 1 ocMem */ 

linclude <0S2.H> 


HSTR 

hstr; 

/* Handle to a string. The handle must 

*/ 



/* have been created with 

*/ 



/* DrgAddStrHandle. 

*/ 

PSZ 

pBuffer; 

/* Buffer where the null -terminated 

*/ 



/* string is returned 

*/ 

ULONG 

ulStrlen; 

/* String length 

*/ 

ULONG 

ulBytesRead; 

/* Number of bytes read 

*/ 

ULONG 

rc; 

/* Return code 

*/ 


ulStrlen = DrgQueryStrNameLen(hstr) + 1; 

rc = DosAl locMem((PVOID *) pBuffer, 

(LONG)ulStrl en, 
fPERM | 

PAG_COMMIT) ; 

j ***************************************************************** J 

/* The ulBytesRead parameter contains the number of bytes */ 

/* actually written to the memory pointed to by pBuffer */ 

J ***************************************************************** j 

ulBytesRead = DrgQueryStrName(hstr, 

ulStrlen, /* Number of bytes to copy */ 
pBuffer) ; 
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DrgQueryStrNameLen 
Get String Length 


#define INCL.WINSTDDRAG 


ULONG DrgQueryStrNameLen (HSTR Hstr) 


This function gets the length of a string associated with a string handle. 

Parameters 

Hstr (HSTR) - input 
String handle. 

The handle must be created with DrgAddStrHandle. 


Returns 

String length. 

0 The string handle is NULLHANDLE or is not valid. 

Other The length of the string associated with the string handle, excluding the null terminating 
byte. 


Possible returns from WinGetLastError 

PMERRINVALID PARAMETERS An application parameter value is invalid for its converted 

PM type. For example: a 4-byte value outside the range 
—32,768 to +32,767 cannot be converted to a SHORT, and 
a negative number cannot be converted to a ULONG or 
USHORT. 


Remarks 

This function should be called before calling the DrgQueryStrName function. It is used to determine 
and allocate the buffer size for the string associated with the string handle. If the input string handle 
is NULLHANDLE or not valid, a length of 0 is returned. 


Related Functions 

• DrgQueryStrName 
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DrgQueryStrNameLen - 
Get String Length 


Example Code 

This example shows how to obtain the length of a string given that the string handle is known. The 
string handle must have been originally created with the DrgAddStrHandle function. 

Idefine INCL_WINSTDDRAG /* Direct Manipulation (Drag) Functions */ 

Idefine INCL_DOSMEMMGR /* Memory Management Functions for */ 

/* DosAllocMem */ 

linclude <0S2.H> 


HSTR 

hstr; 

/* Handle to a string. The handle must 

*/ 



/* have been created with 

*/ 



/* DrgAddStrHandle. 

*/ 

PSZ 

pBuffer; 

/* Buffer where the null -terminated 

*/ 



/* string is returned 

*/ 

ULONG 

ulStrl en; 

/* String length 

*/ 

ULONG 

ulBytesRead; 

/* Number of bytes read 

*/ 

ULONG 

rc; 

/* Return code 

*/ 


ulStrlen = DrgQueryStrNameLen (hstr) + 1; 

rc = DosAllocMem((PVOID *) pBuffer, 

(LONG) ulStrlen, 
fPERM | 

PAG_COMMIT) ; 

/***************************************************************** j 

/* The ulBytesRead parameter contains the number of bytes */ 

/* actually written to the memory pointed to by pBuffer */ 

f ***************************************************************** j 

ulBytesRead = DrgQueryStrName(hstr, 

ulStrlen, /* Number of bytes to copy */ 
pBuffer) ; 
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DrgQuery TrueType - 

Get True Type of Dragged Object 


#define INCL_WINSTDDRAG 


BOOL DrgQueryTrueType (PDRAGITEM pDragitem, ULONG cbBuflen, PSZ pszBuffer) 


This function obtains the true type of a dragged object. 


Parameters 

pDragitem (PDRAGITEM) - input 
Pointer. 

Pointer to the DRAGITEM structure whose true type is to be obtained. 

cbBuflen (ULONG) - input 
Number of bytes. 

Maximum number of bytes to copy to the buffer. 

pszBuffer (PSZ) - output 
Buffer. 

Buffer in which the null-terminated string is to be returned. 


Returns 

Success indicator. 

TRUE Successful completion. 

FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERR INVALID PARAMETERS An application parameter value is invalid for its converted 

PM type. For example: a 4-byte value outside the range 
—32,768 to +32,767 cannot be converted to a SHORT, and 
a negative number cannot be converted to a ULONG or 
USHORT. 

Remarks 

The true type of an object is the first type in the string referenced by hstrType in the DRAGITEM 
structure. 

This function can be called after calling the DrgQueryTrueTypeLen function. If the type string for the 
object is NULLHANDLE, FALSE is returned. 


Related Functions 

Prerequisite Functions 

• DrgQueryTrueTypeLen 

Other Related Functions 

• DrgVerifyTrueType 
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DrgQueryTrueType - 
Get True Type of Dragged Object 


Example Code 

This example shows how to obtain the true type of an object. 

Idefine INCL_WINSTDDRAG /* Direct Manipulation (Drag) Functions */ 
linclude <0S2.H> 


BOOL f Success; /* Return value */ 

DRAGITEM Dragitem; /* DRAGITEM structure whose true type */ 

/* is to be obtained */ 

char szBuffer[32] ; /* Buffer in which the null -terminated */ 

/* string is to be returned */ 


fSuccess = DrgQueryTrueType(&Dragitem, 

sizeof(szBuffer) , 
szBuffer) ; 
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DrgQueryTrueTypeLen - 

Get String Length for True Type of Dragged Object 


#define INCL_WINSTDDRAG 


ULONG DrgQueryTrueTypeLen (PDRAGITEM pDragitem) 


This function obtains the length of the string that represents the true type of a dragged object. 


Parameters 

pDragitem (PDRAGITEM) - input 
Pointer. 

Pointer to the DRAGITEM structure whose true type length is to be obtained. 


Returns 

String length. 

0 Error occurred. 

Other The length of the first element of the character string associated with hstrType, 
excluding the null-terminating byte. 

Possible returns from WinGetLastError 

PMERR INVALID PARAMETERS An application parameter value is invalid for its converted 

PM type. For example: a 4-byte value outside the range 
—32,768 to +32,767 cannot be converted to a SHORT, and 
a negative number cannot be converted to a ULONG or 
USHORT. 


Remarks 

This function can be used to determine the buffer size to allocate for the string representing the true 
type of a dragged object. The true type of an object is the first type in the type string referenced by 
hstrType in the DRAGITEM structure. 

This function can be called before calling the DrgQueryTrueType function. 

If the input string handle is NULLHANDLE or not valid, a length of 0 is returned. 


Related Functions 

• DrgQueryTrueType 
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DrgQueryTrueTypeLen - 
Get String Length for True Type of Dragged Object 

Example Code 

This example shows how to obtain the length of the true type string with the DrgQueryTrueTypeLen 
function. 

Idefine INCL_WINSTDDRAG /* Direct Manipulation (Drag) Functions */ 


Idefine INCL_DOSMEMMGR /* Memory Management Functions for */ 

/* DosAllocMem */ 

linclude <0S2.H> 

PSZ pszBuffer; /* Buffer in which the DRAGITEM */ 

/* structure is stored */ 

BOOL f Success; /* Return value */ 

DRAGITEM Dragitem; /* DRAGITEM structure whose true type */ 

/* length is to be obtained */ 

ULONG rc; /* Return code */ 

ULONG ul Length; /* String length of dragged object */ 


ul Length = DrgQueryTrueTypeLen(&Dragitem) + 1; 

rc = DosAllocMem((PVOID *) pszBuffer, ul Length, fPERM); 

fSuccess - DrgQueryTrueType(&Dragi tern, ulLength, pszBuffer); 
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DrgReleasePS - 
Release Presentation Space 


#define INCL_WINSTDDRAG 


BOOL DrgReleasePS (HPS Hps) 


This function releases a presentation space obtained by using the DrgGetPS function. 

Parameters 

Hps (HPS) - input 

Presentation-space handle. 

Handle of the presentation space to release. 


Returns 

Success indicator. 

TRUE Successful completion. 

FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRINVHPS 
PMERRNOTDRAGGING 

Remarks 

Only presentation spaces created with DrgGetPS can be released using this function. 
The presentation-space handle should not be used after this function. 


Related Functions 

Prerequisite Functions 

• DrgGetPS 


Example Code 

In this example the presentation space handle is retrieved, a bit map is loaded, and the presentation 
space is released with the DrgReleasePS function. 

Idefine INCL_WINSTDDRAG /* Direct Manipulation (Drag) Functions */ 
linclude <os2.h> 

Idefine ID_BITMAP 255 
HPS hps; 

HWND hwnd; 

case DM_DRAGOVER: 

hps = DrgGetPS ( hwnd ) ; 

DrawTargetEmphasis(hps, hwnd); 

DrgReleasePS(hps) ; 


An invalid presentation-space handle was specified. 
A drag operation is not in progress at this time. 
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DrgSendTransferMsg - 
Send Drag Message 


#define INCL_WINSTDDRAG 


MRESULT DrgSendTransferMsg (HWND hwndTo, ULONG uiMsgid, MPARAM mpParaml, 

M PAR AM mpParam2) 


This function sends a message to the other application involved in the direct manipulation operation. 


Parameters 

hwndTo (HWND) - input 
Window handle. 

Window handle to which the message is to be sent: 

Target hwndltem in the DRAGITEM structure. 

Source hwndClient in the DRAGTRANSFER structure. 

uiMsgid (ULONG) - input 
Message identifier. 

Identifier of the message to be sent. Valid messages are: 

DM_ENDCONVERSATION 

DM_RENDER 

DM_RENDERPREPARE 

mpParaml (MPARAM) - input 
mpl for the message. 

mpParam2 (MPARAM) - input 
mp2 for the message. 


Returns 

Message-return data. 


Remarks 

If the message to be sent is DMRENDER or DM_RENDERCOMPLETE, the usReply field in 
DRAGTRANSFER is set to 0 before the message is sent. If the message cannot be sent, FALSE is 
returned. 

When the message to be sent is DM RENDER, DosGiveSeg is called. DosGiveSeg gives access to 
the DRAGTRANSFER structure to the process that owns the window indicated by hwndTo. The use 
count for the segment in which the DRAGTRANSFER structure exists is incremented. 

The process to which the message is being sent must call DrgFreeDragtransfer for the 
DRAGTRANSFER structure before the segment can be freed. 


Related Functions 

• DrgPostTransferMsg 
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DrgSendT ransferMsg 
Send Drag Message 


Example Code 

This function is used to send a message from one window to another when a direct manipulation is in 
progress. In this example, the function is used to inform the target that the operation is complete and 
successful. 

fdefine INCL_WINSTDDRAG /* Direct Manipulation (Drag) Functions */ 
finclude <os2.h> 

PDRAGINFO pdinfo; 

MPARAM mpl; 

TID tid; 


case DM_DR0P: 
pdinfo = (PDRAGINFO) mpl; 

y ************* ************************************************** j 

/* If this is a copy operation, spawn a thread to do the copy */ 

y*************************************************************** J 

if (pdinfo->usOperation == D0_C0PY) 

{ 

DosCreateThread (&ti d , CopyThread, pdinfo, FALSE, 4096); 

} 

break; 


void Copy Thread (PDRAGINFO pdinfo) 

{ 

PDRAGITEM pditem; 

USHORT i ; 

ULONG fl Result; 

HAB hab; 

HMQ hmq; 

char szSource [CCH_MAXPATH] ; 

char szTarget [CCH_MACPATH] ; 


J ******************************************************* ******** J 

/* DrgSendTransferMsg needs a message queue, so create one for */ 
/* this thread */ 

y*************************************************************** j 


hab = Winlnitialize (0); 

hmq = WinCreateMsgQueue (hab, 0); 


y*************************************************************** J 

/* Try to copy each item that was dragged */ 

y*************************************************************** j 

for (i = 0; i < pdinfo->cditem; i++) 

{ 

^************************************************************* J 

/* Get a pointer to the DRAGITEM */ 

y *************************************************************/ 

pditem = DrgQueryDragitemPtr (pdinfo, i); 


j************************************************************* j 

/* If we could query the source and target names, and the */ 
/* copy was successful , return success */ 

y************************************************************* y 

if (DrgQueryStrName (pditem->hstrSourceName, sizeof (szSource), 
szSource) 

DrgQueryStrName (pditem->hstrTargetName, sizeof (szTarget), 
szTarget) 

IDosCopy (szSource, szTarget, 0)) 

{ 

fl Result = DMFL_TARGETSUCCESSFUL; 

} 
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Send Drag Message 


j ************************************************************* j 

/* Otherwise, return failure */ 

j ************************************************************* j 

else 

{ 

fl Result = DMFL_TARGETFAIL; 

} 

^************************************************************* j 

/* Let the source know we're done with this item */ 

j ************************************************************* j 

DrgSendTransferMsg (pditem->hwndltem, DM_ENDCONVERSATION, 
(MPARAM) pditem->ul ItemID, 

(MPARAM) fl Result); 


WinDestroyMsgQueue (hmq); 
WinTerminate (hab); 
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DrgSetDraglmage 
Set Drag Image 


#define INCL_WINSTDDRAG 


BOOL DrgSetDraglmage (PDRAGINFO pDraginfo, PDRAGIMAGE pdimg, ULONG cdimg, 
PVOID pReserved) 


This function sets the image that is being dragged. 


Parameters 

pDraginfo (PDRAGINFO) - input 
Pointer. 

Pointer to the DRAGINFO structure representing the drag operation for which the pointer is to be 
set. 

pdimg (PDRAGIMAGE) - input 
Pointer. 

Pointer to an array of DRAGIMAGE structures. These structures describe the images to be 
drawn under the pointer during the drag. 

cdimg (ULONG) - input 
Array size. 

Size of the pdimg array. 

pReserved (PVOID) - input 
Reserved. 

Must be set to NULL by the caller. 


Returns 

Success indicator. 

TRUE Successful completion. 

FALSE Error occurred. 

Possible returns from WinGetLastError 

The memory block was not allocated properly. 

An application parameter value is invalid for its converted 
PM type. For example: a 4-byte value outside the range 
—32,768 to +32,767 cannot be converted to a SHORT, and 
a negative number cannot be converted to a ULONG or 
USHORT. 

The operation terminated through insufficient memory. 


PMERR_ACCESS_DENIED 

PMERRINVALIDPARAMETERS 


PMERRINSUFFICIENTMEMORY 


Remarks 

The image that is set with DrgSetDraglmage is used only while the pointer is over the target that 
made the call. If the pointer leaves the original target, the new target can specify an image by 
calling DrgSetDraglmage. 

If the new target does not call DrgSetDraglmage, the original image that was supplied on the call to 
DrgDrag is used. 
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Set Drag Image 


Related Functions 

• DrgSetDragPointer 


Example Code 

This example sets the icon image that is displayed during a direct manipulation operation. 


Idefine INCL_GPIBITMAPS 
Idefine INCL_WINSTDDRAG 
linclude <os2.h> 

Idefine ID_BITMAP 257 
HPS hps; 

BOOL fi Result; 

HAB hab; 

PDRAGINFO pdinfo; 

DRAG I MAGE dimg; 

HBITMAP hbm; 

HWND hwnd; 


/* GPI Bit Map Functions */ 

/* Direct Manipulation (Drag) Functions */ 

/* .rc file: "bitmap 257 drgimage.bmp" */ 
/* Presentation space handle */ 


/* Bit-map handle */ 


f ***************************************************************** j 

/* Load a bit map for use as a drag image */ 

^***************************************************************** j 


case WM_CREATE: 

hps = WinGetPS(hwnd) ; 

hbm = GpiLoadBitmap(hps,OL,ID_BITMAP,20L,2OL) ; 

WinReleasePS(hps) ; 

break; 


case DM_DRAGOVER: 


j***************************************************************** j 

/* Initialize the DRAGIMAGE structure */ 

y***************************************************************** y 


dimg.cb = si zeof (DRAGIMAGE) ; 
dimg.cptl = 0; 

dimg.hlmage = hbm; 

dimg.sizlStretch.cx = 20L; 
dimg.sizlStretch.cy = 20L; 
dimg.fl = DRG_BITMAP | 
DRGJTRETCH; 
dimg.cxOffset = 0; 
dimg.cyOffset = 0; 


/* Size control block */ 

/* Image handle passed to */ 
/* DrgDrag */ 
/* Size to stretch ico or */ 
/* bmp to */ 

/* Stretch to size specified */ 
/* Offset of the origin of */ 
/* the image from the pointer*/ 
/* hotspot */ 


y***************************************************************** y 

/* Set the drag image */ 

y***************************************************************** y 


flResult= DrgSetDragImage(pdinfo,&dimg,(ULONG)sizeof(dimg) , NULL) ; 
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DrgSetDragitem - 
Set Values in DRAGITEM 


#define INCL_WINSTDDRAG 


BOOL OrgSetDragitem (PORAGINFO pOraglnfo, PDRAGITEM pDragitem, ULONG cbBuffer, 
ULONG (Item) 


This function sets the values in a DRAGITEM structure. 

Parameters 

pDraginfo (PDRAGINFO) - input 
Pointer. 

Pointer to the DRAGINFO structure in which to place the DRAGITEM. 

pDragitem (PDRAGITEM) - input 
Pointer. 

Pointer to the DRAGITEM structure to place in DRAGINFO. 

cbBuffer (ULONG) - input 
DRAGITEM size. 

Size of the DRAGITEM addressed by pDragitem. 

litem (ULONG) - input 
DRAGITEM index. 

Zero-based index of the DRAGITEM to be set. 

Returns 

Success indicator. 

TRUE Successful completion. 

FALSE Error occurred. 

Remarks 

This function is used to initialize the DRAGINFO structure before calling DrgDrag. 
This function is used only by the source of the drag, not by the target. 


Related Functions 

• DrgQueryDragitem 


Example Code 

This example shows a direct manipulation operation between two windows. The actual operation, 
copying the CONFIG.SYS file to C:\OS2\CONFIG.SYS, is visually represented by a drag and drop of 
an icon. 


Idefine INCL_GPIBITMAPS 
Idefine INCL_WINSTDDRAG 
Idefine INCL_DOSFILEMGR 
Idefine INCL_WININPUT 
linclude <os2.h> 
linclude <string.h> 
Idefine ID_WIND0W 255 
Idefine ID_ITEM 256 
Idefine ID_BITMAP 257 
HPS hps; 


/* GPI Bit Map Functions */ 
/* Direct Manipulation (Drag) Functions */ 
/* File Management Functions */ 
/* Window Input Functions */ 


/* .rc file: "bitmap 257 drgimage.bmp" */ 
/* Presentation space handle */ 
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Set Values in DRAGITEM 


BOOL 

fl Result; 

HAB 

hab; 

PDRAGINFO 

pdinfo; 

DRAGITEM 

ditem; 

DRAGIMAGE 

dimg; 

PDRAGITEM 

pditem; 

HBITMAP 

hbm; 

HPOINTER 

hptr; 

HWND 

hwndDrop ; 

HWND 

hwnd; 

MPARAM 

mpl; 

char szBuffer[32] ; 

char szSource[32] ; 
char szTarget[32] ; 


/* Bit-map handle */ 

/* Pointer bit-map handle */ 


/* Buffer where intersection string */ 
/* is returned */ 


j ******************************************** ********************* y 

/* Inside Cl ientWindowProc of Source Window */ 

y ************************************************** *************** y 


case WM_BEG INDRAG: 


! ***************************************************************** ^ 
/* Initialize the DRAGITEM structure */ 

y ***************************************************************** j 

ditem.hwndltem = hwnd; /* Conversation partner */ 

ditem.ul ItemID = ID_ITEM; /* Identifies item being dragged */ 

ditem.hstrType = DrgAddStrHandle("DRT_TEXT") ; /* Text item */ 

ditem.hstrRMF = DrgAddStrHandl e ( "<DRM_0S2FILE , DRF_TEXT>" ) ; 
ditem.hstrContainerName = DrgAddStrHandle("C:\\“) ; 
ditem.hstrSourceName = DrgAddStrHandle("C:\\CONFIG.SYS") ; 
ditem.hstrTargetName = DrgAddStrHandle("C:\\0S2\\C0NFIG.SYS") ; 
di tern. cxOff set = 0; di tern. cyOff set = 0; 
ditem.fsControl = 0; ditem.fsSupportedOps = 0; 


***************************** *********** ************************ j 

/* Create the DRAGINFO structure */ 

j ***************************************************************** j 


pdinfo = DrgAllocDraginfo(l); 

j *********************************************************** ****** j 

/* Initialize the DRAGIMAGE structure */ 

j **************************** ************************************* J 


dimg.cb = si zeof (DRAGIMAGE) ; /* Size control block */ 

dimg.cptl = 0; 

dimg.hlmage = hbm; /* Image handle passed to */ 

/* DrgDrag */ 

dimg.sizlStretch.cx = 20L; /* Size to stretch ico or */ 

dimg.sizl Stretch. cy = 20L; /* bmp to */ 

dimg.fl = DRG_BITMAP | 

DRG_STRETCH; /* Stretch to size specified */ 

dimg.cxOffset = 0; /* Offset of the origin of the */ 

dimg.cyOffset = 0; /* image from the pointer */ 

/* hotspot */ 

flResult= DrgSetDragitem(pdinfo, &ditem, (ULONG)sizeof(ditem) , 0); 

J ***************************************************************** j 

/* Perform the drag operation: */ 


j ***************************************************************** j 
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Set Values in DRAGITEM 


hwndDrop = DrgDrag(hwnd, /* Source of the drag */ 

pdinfo, /* Pointer to DRAGINFO structure */ 

(PDRAGIMAGE)&dimg, /* Drag image */ 

1, /* Size of the pdimg array */ 

VK_ENGDRAG, /* Release of drag button */ 

/* terminates the drag */ 

NULL) ; /* Reserved */ 

/ *****************************************************************/ 
/* Inside Cl ientWindowProc of Target Window */ 


/***************************************************************** j 


case DM_DRAGOVER: 

pdinfo = MPFROMP(mpl); 

pditem = DrgQueryDragitemPtr(pdinfo,0) ; 

flResult = DrgVerifyTrueType(pditem,"DRF_TEXT"); 

i f ( ! f 1 Result) 

y***************************************************************** j 

/* Inform the application that you will accept the drop */ 

j ***************************************************************** j 

return (MRFR0M2SH0RT ( D0R_DR0P , D0_C0P Y) ) ; 

case DMDROP: 

pdinfo = MPFROMP(mpl) ; 

pditem = DrgQueryDragitemPtr(pdinfo.O) ; 

j ***************************************************************** j 

/* Perform the operation represented by the direct manipulation */ 

j ********************************************************** ******* j 

DrgQueryStrName(pditem->hstrSourceName,sizeof(szSource) .szSource) ; 
DrgQueryStrName(pditem->hstrTargetName,sizeof(szTarget) .szTarget) ; 
flResult = DosCopy(szSource, szTarget, 0L) ; 

^***************************************************************** j 

/* If operation is successful, return DMFL_TARGETSUCCESSFUL */ 

J ***************************************************************** j 

if(!fl Result) 

{ 

DrgSendT ransf erMsg ( pdi tem->hwndl tern , 

DM_ENDCONVERSATION , 

MPFROMLONG (pdi tem->ul ItemID) , 
MPFROMLONG(DMFL_TARGETSUCCESSFUL) ) ; 

} 

/***************************************************************** j 

/* Otherwise, return DMFL_TARGETFAIL */ 

y***************************************************************** j 

else 

{ 

DrgSendT ransf erMsg ( pd i tem->hwnd Item, 

DM_ENDCONVERSATION , 

MPFROMLONG ( pdi tem->ul ItemID) , 

MPFROMLONG (DMFL_TARGETFAI L) ) ; 

} 
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DrgSetDragPointer - 
Set Pointing Device Pointer 


#define INCL_WINSTDDRAG 


BOOL DrgSetDragPointer (PDRAGINFO pDraglnfo, HPOINTER hptrHandle) 


This function sets the pointer to be used while over the current target. 

Parameters 

pDraglnfo (PDRAGINFO) - input 
Pointer. 

Pointer to the DRAGINFO structure to be used for this drag. 

hptrHandle (HPOINTER) - input 
Pointer handle. 

Handle to the pointer to use. 

Returns 

Success indicator. 

TRUE Successful completion. 

FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERR INVALID HPTR An invalid pointer handle was specified. 

Remarks 

This function sets the pointer to be used to indicate the hot spot while dragging over the current 
target. 

The pointer that is set with DrgSetDragPointer is used only while it is over the current target. The 
pointer is reset to the default when a new target is dragged over. 

This function can be used by an application to provide meaningful augmentation emphasis for an 
operation that is unknown to the system (for example, swap). 

When the drag pointer is successfully set, TRUE is returned. 

Related Functions 

• DrgSetDraglmage 
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Set Pointing Device Pointer 


Example Code 

This example uses the DrgSetDragPointer function to set the image used for the pointer while the 
pointer is over the target during a direct manipulation operation. 

Idefine INCL_WINSTDDRAG /* Direct Manipulation (Drag) Functions */ 
linclude <0S2.H> 

BOOL fl Result; 

PDRAGITEM pditem; 

HPOINTER hptrCrossHair; 

MPARAM mpl; 

char szBuffer[32] ; 

case DM_DRAGOVER: 

DrgSetDragPointer ( (PDRAGINFO) mpl, hptrCrossHair); 
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Verify Native Rendering Mechanism and Format 


#define INCL_WINSTDDRAG 


BOOL DrgVerifyNativeRMF (PDRAGITEM pDragltem, PSZ pszRMF) 


This function determines if the native rendering mechanism and format of an object match any 
supplied by the application. 


Parameters 

pDragltem (PDRAGITEM) - input 
Pointer. 

Pointer to the DRAGITEM structure whose native rendering mechanism and format are to be 
verified. 

pszRMF (PSZ) - input 
String. 

A string specifying the rendering mechanism and format. The string is of the form: 
mechfmt[,mechfmt,mechfmt„..], where mechfmt can be in either of these formats: 

• <mechanism(1),format(1)> 

• (mechanism(1)[, mechanism(n)...]) (format(1)[,format(n)...]) 


Returns 

Validity indicator. 

TRUE Successful completion. 

FALSE Error occurred. 

Remarks 

This function determines if the native rendering mechanism and format of a dragged object are 
understood by the target. 

If TRUE is returned, the target may be able to carry out the action indicated by the direct 
manipulation itself, or it can select the native rendering mechanism and format as those to be used 
for the data exchange. 


Related Functions 

• DrgQueryNativeRMF 
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Drg Verify NativeRMF - 

Verify Native Rendering Mechanism and Format 


Example Code 

This example determines if the native rendering mechanism and format of an object match any 
supplied by the application. 

Idefine INCL_WINSTDDRAG /* Direct Manipulation (Drag) Functions */ 
linclude <0S2.H> 


DRAGITEM Dragitem; /* DRAGITEM structure whose native */ 

/* rendering mechanism and format are */ 
/* to be verified */ 

char pszRMF[25]; /* A string specifying the rendering */ 

/* mechanism and format. The string is */ 
/* of the form: */ 

/* */ 
/* mechfmt[,mechfmt,mechfmt,.. .] , */ 

/* */ 
/* where 'mechfmt' can be in either of */ 
/* these formats: */ 

/* */ 
/* o <mechanism(l) .format (1)> */ 

/* o (mechanism(l) [, mechanism(n) . . .] ) */ 
/* (format(l)[,format(n)...]) */ 


strcpy (pszRMF, " (DRM_0S2FILE,DRF_TEXT) ") ; 

/* Mechanism is an OS/2 file and format */ 
/* is a null -terminated string. See */ 
/* the DRAGITEM structure for valid */ 
/* formats. */ 


i f (DrgVeri fyNati veRMF(&Dragi tern, pszRMF) ) 

{ 

/* Code block 


} 


*/ 
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Verify Given Rendering Mechanism and Format 


#define INCL_WINSTDDRAG 


BOOL DrgVerifyRMF (PDRAGITEM pDragltem, PSZ pszMech, PSZ pszFormat) 


This function determines if a given rendering mechanism and format are supported for a dragged 
object. 


Parameters 

pDragltem (PDRAGITEM) - input 
Pointer. 

Pointer to the DRAGITEM structure whose native rendering mechanism and format are to be 
validated. 

pszMech (PSZ) - input 
Mechanism string. 

A string specifying the rendering mechanism to search for. NULL will match any mechanism. 

pszFormat (PSZ) - input 
Format string. 

A string specifying the rendering format to search for. NULL will match any format. 


Returns 

Validity indicator. 

TRUE Successful completion. 

FALSE Error occurred. 

Remarks 

This function determines if a given rendering mechanism and format ordered pair are represented in 
the set of valid pairs specified by hstrRMF for the dragged object. 

Related Functions 

• DrgVerifyNativeRMF 
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DrgVerifyRMF - 

Verify Given Rendering Mechanism and Format 

Example Code 

This example determines if a given rendering mechanism and format are supported for a dragged 
object. 

fdefine INCL_WINSTDDRAG /* Direct Manipulation (Drag) Functions */ 
linclude <0S2.H> 

DRAGITEM Dragitem; /* DRAGITEM structure whose native */ 

/* rendering mechanism and format are */ 

/* to be validated */ 

char pszMech[] = "DRM_0S2FILE"; 

/* A string specifying the rendering */ 

/* mechanism to search for */ 

char pszFormat[] = "DRF_TEXT"; 

/* A string specifying the rendering */ 

/* format to search for */ 

if(DrgVerifyRMF(&Dragitem, pszMech, pszFormat)) 

/* Mechanism is an OS/2 file and format */ 

/* is a null -terminated string */ 

{ 

/* Code block */ 

} 
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Verify True Type of Dragged Object 


#define INCL_WINSTDDRAG 


BOOL DrgVerifyTrueType (PDRAGITEM pDragltem, PSZ pszType) 


This function determines if the true type of a dragged object matches an application-supplied type 
string. 


Parameters 

pDragltem (PDRAGITEM) - input 
Pointer. 

Pointer to the DRAGITEM structure whose true type is to be verified. 

pszType (PSZ) - input 
Type string. 

A string specifying a type. This string is in the format: type[, type...]. 


Returns 

Validity indicator. 

TRUE Successful completion. 

FALSE Error occurred. 

Remarks 

If an item in the string pointed to by pszType matches the first type in the string associated with 
hstrType in the DRAGITEM structure, TRUE is returned. 

A target application uses this function to determine if it supports the true type of a dragged object. If 
the application does not support the true type, it can either disallow a drop or change its default 
operation. If the default operation is a move, the drop should be disallowed, or the operation 
changed to a copy to prevent any loss of data for the object. 


Related Functions 

• DrgQueryTrueType 

• DrgVerifyType 

• DrgVerifyTypeSet 
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Verify True Type of Dragged Object 


Example Code 

This example verifies whether a given type is present in the list of types defined for a drag object. 

fdefine INCL_WINSTDDRAG /* Direct Manipulation (Drag) Functions */ 
linclude <0S2.H> 

BOOL fValid; 

DRAGITEM Dragitem; /* DRAGITEM structure whose hstrType is */ 


/* to be verified */ 

char pszType[8]; /* A string specifying the types to */ 

/* search for */ 

strcpy(pszType,"DRT_EXE"); /* Executable file type. See the */ 

/* DRAGINFO structure for valid */ 

/* types. */ 


fValid = DrgVerifyTrueType(&Dragitem, pszType); 
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Verify Type of Dragged Object 

#define INCL_WINSTDDRAG 


BOOL DrgVerifyType (PDRAGITEM pDragitem, PSZ pszType) 


This function verifies whether a given type is present in the list of types defined for a drag object. 

Parameters 

pDragitem (PDRAGITEM) - input 
Pointer. 

Pointer to the DRAGITEM structure whose hstrType is to be verified. 

pszType (PSZ) - input 
Type string. 

A string specifying the types to search for. This string is in the format: type[,type...]. 

Returns 

Success indicator. 

TRUE Successful completion. 

FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERR INVALID PARAMETERS An application parameter value is invalid for its converted 

PM type. For example: a 4-byte value outside the range 
—32,768 to +32,767 cannot be converted to a SHORT, and 
a negative number cannot be converted to a ULONG or 
USHORT. 

PMERR INSUFFICIENT MEMORY The operation terminated through insufficient memory. 

Remarks 

If at least one of the types specified by pszType is present in hstrType in the DRAGITEM structure, 
TRUE is returned. 

Related Functions 

• DrgVerifyTrueType 

• DrgVerifyTypeSet 
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DrgVerifyType - 

Verify Type of Dragged Object 


Example Code 

This example verifies whether a given type is present in the list of types defined for a drag object. 

Idefine INCL_WINSTDDRAG /* Direct Manipulation (Drag) Functions */ 
linclude <0S2.H> 


BOOL fValid; 

DRAGITEM Dragitem; /* DRAGITEM structure whose hstrType is */ 

/* to be verified */ 

char pszType[] = "DRT_EXE"; 

/* A string specifying the types to */ 
/* search for */ 

fValid = DrgVerifyType(&Dragitem, pszType); 
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Verify Types 


#define INCL_WINSTDDRAG 


BOOL DrgVerifyTypeSet (PDRAGITEM pDragitem, PSZ pszType, ULONG cbBuflen, 
PSZ pszBuffer) 


This function returns the intersection of the contents of the string associated with the type-string 
handle for an object and an application-specified type string. 


Parameters 

pDragitem (PDRAGITEM) - input 
Pointer. 

Pointer to the DRAGITEM structure whose hstrType is to be verified. 

pszType (PSZ) - input 
Type string. 

A string specifying the types to search for. This string is in the format: type[,type...]. 

cbBuflen (ULONG) - input 
Buffer size. 

Size of the return buffer. The buffer should be at least one byte longer than the length of the 
string pointed to by pszType. 

pszBuffer (PSZ) - output 
Buffer. 

Buffer where the intersection string is returned. 


Returns 

Match indicator. 

TRUE Successful completion. 

FALSE Error occurred. 

Remarks 

If at least one of the types specified by pszType is present in hstrType in the DRAGITEM structure, 
TRUE is returned. 

Related Functions 

• DrgVerifyType 

• DrgVerifyTrueType 
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DrgVerifyTypeSet 
Verify Types 


Example Code 

In this example, the DrgVerifyTypeSet function is used to determine whether DRT_TEXT is among 
the types associated with the object. If it is, the drop is accepted. 

Idefine INCL_WINSTDDRAG /* Direct Manipulation (Drag) Functions */ 
linclude <0S2.H> 
linclude <stdio.h> 

BOOL fl Result; 

DRAGITEM pditem; 
char szBuffer[32] ; 

case DM_DRAGOVER: 

flResult = DrgVerifyTypeSet(&pditem, 

"DRT_TEXT" , 
sizeof(szBuffer) , 
szBuffer) ; 

flResult = strcmp(szBuffer,"DRT_TEXT") ; 

j************************************************************** j 

/* See if the object is an OS/2 file as well as being of text */ 

/* format. AND result flag with previous result flag to get */ 

/* the "effective" return code. */ 

f ************************************************************** j 

flResult = Dr g Ver i f yRM F ( &pd i t em , " DRM_0S2 FILE"," DRF_TEXT" ) ; 

y************************************************************** y 

/* See if DRT_TEXT is the true type of the object */ 

j ************************************************************** j 

flResult = DrgVerifyTrueType(&pditem,"DRF_TEXT“) ; 
i f ( ! f 1 Result) 

j ************************************************************** j 

/* Inform the application that you will accept the drop */ 

j ************************************************************** j 

return (MRFR0M2SH0RT ( D0R_DR0P , D0_C0PY)); 
break; 
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Chapter 4. Dynamic Data Formatting Functions 


The following table shows all the dynamic data formatting (Ddf) functions in alphabetic order. 


C Name 

DdfBeginList 

DdfBitmap 

DdfEndList 

DdfHyperText 

Ddflnform 

Ddflnitialize 

DdfListltem 

DdfMetafile 

DdfPara 

DdfSetColor 

DdfSetFont 

DdfSetFontStyle 

DdfSetFormat 

DdfSetTextAlign 

Ddf Text 
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DdfBeginList - 
Begin Definition List 


#define INCL_DDF 


BOOL DdfBeginList (HDDF hddf, ULONG uiWidthDT, ULONG fBreakType, ULONG fSpacing) 


This function begins a definition list in the DDF buffer; it corresponds to the :dl. (definition list) tag. 

Parameters 

hddf (HDDF) - input 

Handle to DDF returned by Ddflnitialize. 
uiWidthDT (ULONG) - input 
Width of the definition term. 
fBreakType (ULONG) - input 

Only the following constants may be specified: 

HMBT_ALL Start all definition descriptions on the next line, regardless of the actual 

lengths of definition terms. 

HMBT_FIT Start definition description on the next line only when the definition term 

is longer than the width specified. 

HMBT_NONE Do not start the definition description on the next line, even when the 

definition term is longer than the width specified. 

fSpacing (ULONG) - input 

Only the following constants may be specified: 

HMLS_SINGLELINE Do not insert a blank line between each definition description and the 
next definition term. 

HMLS_DOUBLELINE Insert a blank line between each definition description and the next 
definition term. 

Returns 

Success indicator. 

TRUE Successful completion. 

FALSE Error occurred. 

Possible returns from WinGetLastError 

HMERRDDFMEMORY 
HMERRDDFLISTUNCLOSED 
HMERRDDFLISTBREAKTYPE 
HMERRDDFLISTSPACING 

Remarks 

Once this function has been called, use of any DDF function other than DdfListltem, DdfSetColor, and 
DdfEndList may produce unpredictable results. 


Not enough memory is available. 

An attempt was made to nest a list. 
The value of BreakType is not valid. 
The value for Spacing is not valid. 
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DdfBeginList - 
Begin Definition List 


Related Functions 

• DdfText 

• DdfSetTextAlign 

• DdfSetFormat 

• DdfSetFontStyle 

• DdfSetFont 

• DdfSetColor 

• DdfPara 

• DdfMetafile 

• DdfListltem 

• Ddflnitialize 

• Ddflnform 

• Ddf HyperText 

• DdfEndList 

• DdfBitmap 

Example Code 

After initializing a DDF buffer with Ddflnitialize, the example uses DdfBeginList to indicate the 
beginning of a definition list in the DDF buffer (this corresponds to the IPF dl tag). For a more 
detailed example and discussion of initializing DDF, see the Ddflnitialize sample. 


Idefine INCL_WINWINDOWMGR /* General window management */ 

Idefine INCL_WINMESSAGEMGR /* Message management */ 

Idefine INCL_DDF /* Dynamic Data Facility */ 

linclude <os2.h> 
linclude <pmhelp.h> 

struct _LISTITEM /* definition list */ 


PSZ Term; 

PSZ Desc; 

} Definition[2] = {{"MVS", "Multiple Virtual 
System"}, 

{"VM", "Virtual Machine"}}; 

MRESULT Wi ndowProc.( HWND hwnd, ULONG ulMsg, MPARAM mpl, MPARAM mp2) 

{ 

HWND hwndParent; 

HWND hwndlnstance; 

HDDF hDdf; /* DDF handle */ 

SHORT i; /* loop index */ 

switch( ulMsg ) 

{ 

case HM_QUERY_DDF_DATA: 

/* get the help instance */ 
hwndParent = WinQueryWindow( hwnd, QW PARENT ); 
hwndParent = WinQueryWindow( hwndParent, QW_PARENT ); 
hwndlnstance = (HWND)WinSendMsg( hwndParent, HM QUERY, 

MPFR0MSH0RT( HMQW_INSTANCE ), NULL ); 

/* Allocate IK Buffer (default) */ 
hDdf = Ddflnitialize( 

hwndlnstance, /* Handle of help instance */ 

0L, /* Default buffer size */ 

0L /* Default increment */ 

); 
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Begin Definition List 


if (hDdf == NULLHANDLE) /* Check return code 

{ 

return (MRESULT) FALSE; 

} 

/* begin definition list */ 

if ( ! Ddf Begi nLi st (hDdf , 3L, HMBT_ALL, HMLSJINGLELINE)) 

{ 

return (MRESULT) FALSE; 

} 

/* insert 2 entries into definition list */ 
for (i =0; i < 2; i++) 

{ 

if ( ! Ddf Li stItem(hDdf , Def i ni ti on [i ] .Term, 
Definition^] .Desc)) 

{ 

return (MRESULT) FALSE; 

} 

} 

/* terminate definition list */ 
if ( ! Ddf EndLi s t ( hDdf) ) 

{ 

return (MRESULT) FALSE; 

} 

return (MRESULT) hDdf; 

} 

} 
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DdfBitmap - 
Place Bitmap Reference 


^define INCL_DDF 


BOOL DdfBitmap (HDDF hddf, H BITMAP hbm, ULONG fAIIgn) 


This function places a reference to a bit map in the DDF buffer. 


Parameters 

hddf (HDDF) - input 

Handle to DDF returned by Ddflnitialize. 
hbm (HBITMAP) - input 

Standard Presentation Manager bit map handle. 
fAIIgn (ULONG) - input 


Any of the following values can be specified: 


ART_LEFT 

ART_RIGHT 

ARTCENTER 

ARTRUNIN 


Left-justify the bit map. 

Right-justify the bit map. 

Center the bit map. 

Allow the bit map to be reflowed with text. 


Returns 

Success indicator. 

TRUE Successful completion. 

FALSE Error occurred. 

Not enough memory is available. 
The alignment type is not valid. 


Possible returns from WinGetLastError 

HMERRDDFMEMORY 
H M E R R_DDF_ ALIGNTYPE 


Remarks 

The handle to the presentation space in which the bit map was created cannot be freed by the 
application while the panel is displayed. 

Note: There is a (3-byte + size of HBITMAP structure) ESC code overhead in the DDF internal buffer 
for this function. There is a 1-byte ESC code overhead required for the Align flag. 


Related Functions 

• DdfText 

• DdfSetTextAlign 

• DdfSetFormat 

• DdfSetFontStyle 

• DdfSetFont 

• DdfSetColor 

• DdfPara 

• DdfMetafile 

• DdfListltem 
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DdfBitmap - 

Place Bitmap Reference 


• Ddf Initialize 

• Ddflnform 

• DdfHyperText 

• DdfEndList 

• DdfBeginList 


Example Code 

After initializing a DDF buffer with Ddflnitialize, the example obtains a device context (DevOpenDC), 
creates a presentation space (GpiCreatePS), and loads a bit map (GpiLoadBitmap). It then uses 
DdfBitmap to place a reference to the bit map in the DDF buffer. For a more detailed example and 
discussion of initializing DDF, seethe Ddflnitialize sample. 


Idefine INCL_WINWINDOWMGR /* General window management */ 

Idefine INCL_WINMESSAGEMGR /* Message management */ 

Idefine INCL_GPICONTROL /* Basic PS control */ 

Idefine INCL_GPIBITMAPS /* Bit maps and Pel Operations */ 

Idefine INCL_GPIPRIMITIVES /* Drawing Primitives/Attributes*/ 

Idefine INCL_DDF /* Dynamic Data Facility */ 

linclude <os2.h> 
linclude <pmhelp.h> 


Idefine ACVP_HAB 12 
Idefine BM_HPS 16 
Idefine BM_HDC 20 
Idefine BM_HWND 24 
Idefine ID_LEFT 255 

MRESULT WindowProc( HWND hwnd, ULONG ulMsg, MPARAM mpl, MPARAM mp2 ) 


{ 

HWND hwndParent; /* parent window */ 
HWND hwndlnstance; /* help instance window */ 
HDDF hDdf; /* DDF handle */ 
HDC hdc; /* device context handle */ 
HPS hps; /* presentation space handle */ 
HAB. hab; /* anchor block handle */ 
SIZEL sizel = {OL.OL} ;/* size of new PS */ 
HBITMAP hBitmap; /* bit. map handle */ 
HMODULE hModule; /* module handle */ 


switch( ulMsg ) 

{ 

case HM_QUERY_DDF_DATA : 

hwndParent = WinQueryWindow( hwnd, QW PARENT ); 
hwndParent = WinQueryWindow( hwndParent, QW_PARENT ); 
hwndlnstance = (HWND)WinSendMsg( hwndParent, HM_QUERY, 

MPFROMSHORT ( HMQWINSTANCE ), NULL ); 


/* Allocate IK Buffer (default) */ 
hDdf = Ddflnitialize( 

hwndlnstance, /* Handle of help instance */ 

QL, /* Default buffer size */ 

QL /* Default increment */ 

); 

if (hDdf == NULLHANDLE) /* Check return code */ 

{ 

return (MRESULT) FALSE; 

} 

/* get module handle for bit map */ 
DosGetModHandle("bitmap", &hModule) ; 
if (hModule == NULLHANDLE) 

{ 
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Place Bitmap Reference 


return (MRESULT) FALSE; 

} 

/* get hab for this window */ 

if ((hab = ( HAB)Wi nQueryWi ndowULong ( hwnd , ACVP_HAB)) == NULLHANDLE) 

{ 

return (MRESULT) FALSE; 

} 


/* 

if 

{ 

} 


create a device context */ 

((hdc = DevOpenDC(hab, 0D_MEM0RY , OL, 

(PDEVOPENDATA)NULL, (HDC)NULL) ) == NULLHANDLE) 

return (MRESULT) FALSE; 


/* save hdc in reserved word */ 

Wi nSetWi ndowULong ( hwnd , BM_HDC, (ULONG)hdc) ; 


/* create a noncached micro presentation space */ 

/* and associate it with the window */ 

if ((hps = GpiCreatePS(hab, hdc, fcsizel, PU_PELS | 


GPIF DEFAULT 


{ 

} 


| GPIT_MICRO | GPIA_ASSOC) ) == NULLHANDLE) 
return (MRESULT) FALSE; 


/* save hps in reserved word */ 

Wi nSetWi ndowULong (hwnd, BM_HPS, (ULONG)hps); 


/* Load the Bit map to display */ 

if ((hBitmap = GpiLoadBitmap(hps, hModule, ID_LEFT, 300L, 

300L)) == NULLHANDLE) 


{ 

return (MRESULT) FALSE; 


} 


/* save bit map hwnd in reserved word */ 

Wi nSetWi ndowULong (hwnd, BM_HWND , (ULONG)hBitmap) ; 

/* Display the bit map align left */ 
if (!DdfBitmap(hDdf, hBitmap, (ULONG)TA_LEFT) ) 

{ 

return (MRESULT) FALSE; 

} 

return (MRESULT) hDdf; 


case WM_CL0SE: 

/* release PS, DC, and bit map */ 

GpiDestroyPS((HPS)Wi nQueryWi ndowULong (hwnd, BM_HPS) ) ; 

DevCl oseDC ( (HDC)Wi nQueryWi ndowULong ( hwnd , BMHDC) ) ; 
GpiDeleteBitmap((HBITMAP)WinQueryWindowULong(hwnd, BM HWND)) ; 
Wi nDestroyWi ndow(Wi nQueryWi ndow(hwnd, QWPARENT) ) ; 
return (MRESULT)TRUE; 

} 

} 
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DdfEndList - 
End Definition List 


#define INCL_DDF 


BOOL DdfEndList (HDDF hddf) 


This function terminates the definition list initialized by DdfBeginList. 


Parameters 

hddf (HDDF) - input 

Handle to DDF returned by Ddflnitialize. 


Returns 

Success indicator. 

TRUE Successful completion. 

FALSE Error occurred. 

Possible returns from WinGetLastError 

HMERR_DDF LIST UNINITIALIZED No definition list has been initialized by DdfBeginList. 

Related Functions 

• DdfText 

• DdfSetTextAlign 

• DdfSetFormat 

• DdfSetFontStyle 

• DdfSetFont 

• DdfSetColor 

• DdfPara 

• DdfMetafile 

• DdfListltem 

• Ddflnitialize 

• Ddflnform 

• Ddf HyperText 

• DdfBitmap 

• DdfBeginList 

Example Code 

After initializing a DDF buffer with Ddflnitialize, the example uses DdfBeginList to indicate the 
beginning of a definition list in the DDF buffer (this corresponds to the IPF dl tag). For a more 
detailed example and discussion of initializing DDF, see the Ddflnitialize sample. 


Idefine INCL_WINWINDOWMGR /* General window management */ 

Idefine INCL_WINMESSAGEMGR /* Message management */ 

Idefine INCL_DDF /* Dynamic Data Facility */ 

linclude <os2.h> 
linclude <pmhelp.h> 

struct _L I ST ITEM /* definition list */ 

{ 

PSZ Term; 
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End Definition List 


PSZ Desc; 

} Definition[2] = {{"MVS", "Multiple Virtual 
System"}, 

{"VM", "Virtual Machine"}}; 

MRESULT WindowProc( HWND hwnd, ULONG ulMsg, MPARAM mpl, MPARAM mp2) 

{ 

HWND hwndParent ; 

HWND hwndlnstance; 

HDDF hDdf; /* DDF handle */ 

SHORT i; /* loop index */ 

switch ( ulMsg ) 

{ 

case HMQUERYDDFDATA : 

/* get the help instance */ 
hwndParent = WinQueryWindow( hwnd, QW_PARENT ); 
hwndParent = WinQueryWindow( hwndParent, QW_PARENT ); 
hwndlnstance = (HWND)WinSendMsg( hwndParent, HM QUERY, 

MPFR0MSH0RT( HMQWINSTANCE ) , NULL ) ; 


/* Allocate IK Buffer (default) */ 
hDdf = Ddflnitial ize( 

hwndlnstance, /* Handle of help instance */ 
0L, /* Default buffer size */ 
0L /* Default increment */ 
); 


if (hDdf == NULLHANDLE) /* Check return code */ 

{ 

return (MRESULT) FALSE; 

} 


/* begin definition list */ 

if ( ! Ddf Begi nLi st ( hDdf , 3L, HMBT_ALL, HMLS_SINGLELINE) ) 

{ 

return (MRESULT) FALSE; 

} 


/* insert 2 entries into definition list */ 
for (i=0; i < 2; i++) 

{ 

if (!DdfListItem(hDdf, Def i ni t i on [i ] .Term, 
Def i ni ti on [i ] .Desc)) 

{ 

return (MRESULT) FALSE; 

} 

} 


/* terminate definition list */ 
if ( ! DdfEndLi st(hDdf ) ) 

{ 

return (MRESULT) FALSE; 

} 

return (MRESULT) hDdf; 

} 

} 
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Ddf HyperText - 
Define Hypertext Link 


#define INCL_DDF 


BOOL DdIHyperText (HDDF hddf, PSZ pszText, PSZ pszReference, ULONG IReferenceType) 


This function defines a hypertext link to another panel. 


Parameters 

hddf (HDDF) - input 

Handle to DDF returned by Ddflnitialize. 
pszText (PSZ) - input 
Hypertext phrase. 
pszReference (PSZ) - input 

The value of this parameter depends on the value of ReferenceType: 

- If ReferenceType is REFERENCE_BY_RES, this parameter must contain a pointer to a 
numeric string containing the res number; otherwise it will default to a res number of zero. 
Valid values are 1 -64000; all other values are reserved. 

- If ReferenceType is REFERENCE_BY_ID, this parameter contains a pointer to a string 
containing the alphanumeric identifier of the destination panel. 

f ReferenceType (ULONG) - input 

This parameter specifies whether you are linking via a resource identifier (res number) or via an 
alphanumeric identifier. 

REFERENCE_BY_RES To link via a resource identifier. 

REFERENCE_BY_ID To link via an alphanumeric identifier. 


Returns 

Success indicator. 

TRUE Successful completion. 

FALSE Error occurred. 

Possible returns from WinGetLastError 

HMERR DDF MEMORY Not enough memory is available. 

HMERR_DDF_REFTYPE The reference type is not valid. 

Remarks 

Note: There is a 3-byte ESC code overhead in the DDF internal buffer for each word in the text 

buffer. There is a 1-byte ESC code overhead for each blank and for each newline character. 

If ReferenceType is REFERENCE_BY_ID, then there is a (3-byte + Reference length) ESC code 
overhead. For a ReferenceType of REFERENCE_BY_RES, the overhead is 5 bytes. Finally, 
there is a 3-byte ESC code overhead that is required for ending the hypertext link. 
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Ddf HyperText - 
Define Hypertext Link 


Related Functions 

• Ddf Text 

• DdfSetTextAlign 

• DdfSetFormat 

• DdfSetFontStyle 

• DdfSetFont 

• DdfSetColor 

• DdfPara 

• DdfMetafile 

• DdfListltem 

• Ddflnitialize 

• Ddflnform 

• DdfEndList 

• DdfBitmap 

• DdfBeginList 

Example Code 

After initializing a DDF buffer with Ddflnitialize, the example uses DdfHyperText to create a hypertext 
link with another resource. For a more detailed example and discussion of initializing DDF, see the 
Ddflnitialize sample. 

Idefine INCL_WINWINDOWMGR 
Idefine INCL_WINMESSAGEMGR 
Idefine INCL_DDF 
linciude <os2.h> 
linclude <pmhelp.h> 

PSZ Text = "This text is a HYPERTEXT message. \n"; /* hypertext 

string */ 

PSZ Res ID = "1"; /* Resource identifier */ 

MRESULT WindowProc( HWND hwnd, ULONG ulMsg, MPARAM mpl, MPARAM mp2 ) 

{ 

HWND hwndParent ; 

HWND hwndlnstance; 

HDDF hDdf; /* DDF handle */ 

switch( ulMsg ) 

{ 

case HM_QUERY_DDF_DATA : 

/* get the help instance */ 
hwndParent = WinQueryWindow( hwnd, QW_PARENT ); 
hwndParent = WinQueryWindow( hwndParent, QW_PARENT ); 
hwndlnstance = (HWND)WinSendMsg( hwndParent, HM_QUERY, 

MPFROMSHORT ( HMQW_INSTANCE ), NULL ); 


/* General window management */ 
/* Message management */ 
/* Dynamic Data Facility */ 
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Define Hypertext Link 


} 


/* Allocate IK Buffer (default) */ 


hDdf = Ddflnitial ize( 

hwndlnstance, 

OL. 

OL 

); 


/* Handle of help instance */ 
/* Default buffer size */ 
/* Default increment */ 


if (hDdf = NULLHANDLE) /* Check return code */ 

{ 

return (MRESULT) FALSE; 

} 


/* create hypertext link with resource 1 */ 
if ( ! Ddf HyperT ext ( hDdf , (PSZ)Text, ResID, REFERENCE_BY_RES) ) 
{ 

return (MRESULT) FALSE; 

} 

return (MRESULT) hDdf; 
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Ddflnform - 
Define Inform Link 


#define INCL_DDF 


BOOL Ddflnform (HDDF hddf, PSZ pszText, ULONG resInformNumber) 


This function defines a hypertext inform link; it corresponds to the link tag with reftype= inform. 


Parameters 

hddf (HDDF) - input 

Handle to DDF returned by Ddflnitialize. 
pszText (PSZ) - input 
Hypertext phrase. 

resInformNumber (ULONG) - input 

Res number associated with this hypertext field. Possible values are 1 to 64000; all other values 
are reserved. 

Returns 

Success indicator. 

TRUE Successful completion. 

FALSE Error occurred. 

Possible returns from WinGetLastError 

HMERR DDF MEMORY Not enough memory is available. 

Related Functions 

• DdfText 

• DdfSetTextAlign 

• DdfSetFormat 

• DdfSetFontStyle 

• DdfSetFont 

• DdfSetColor 

• DdfPara 

• DdfMetafile 

• DdfListltem 

• Ddflnitialize 

• Ddf HyperText 

• DdfEndList 

• DdfBitmap 

• DdfBeginList 


Example Code 

After initializing a DDF buffer with Ddflnitialize, the example uses Ddflnform to create a hypertext 
inform link with another resource (corresponds to the IPF dink, tag with reftype = inform). For a more 
detailed example and discussion of initializing DDF, see the Ddflnitialize sample. 

Idefine INCL_WINWINDOWMGR /* General window management */ 

Idefine I NCL_WI NMESSAGEMGR /* Message management */ 

Idefine INCL_DDF /* Dynamic Data Facility */ 

linclude <os2.h> 
linclude <pmhelp.h> 
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Define Inform Ljnk 


PSZ Text = "This text is a HYPERTEXT message. \n"; /* hypertext 

string */ 

MRESULT WindowProc( HWND hwnd, ULONG ulMsg, MPARAM mpl, MPARAM mp2 ) 

{ 

HWND hwndParent; 

HWND hwndlnstance; 

HDDF hDdf; /* DDF handle */ 

switch ( ulMsg ) 

{ 

case HM_QUERY_DDF_DAT A : 

/* get the help instance */ 
hwndParent = WinQueryWindow( hwnd, QW_PARENT ); 
hwndParent = WinQueryWindow( hwndParent, QW_PARENT ); 
hwndlnstance = (HWND)WinSendMsg( hwndParent, HM_QUERY, 

MPFR0MSH0RT( HMQW_INSTANCE ), NULL ); 

/* Allocate IK Buffer (default) */ 
hDdf = Ddf Ini ti al i ze ( 

hwndlnstance, /* Handle of help instance */ 

0L, /* Default buffer size */ 

0L /* Default increment */ 

); 

if (hDdf == NULLHANDLE) /* Check return code */ 

{ 

return (MRESULT) FALSE; 

} 

/* create hypertext inform link with resource 1 */ 
if (!DdfInform(hDdf, (PSZ)Text, 1L) ) 

{ 

return (MRESULT) FALSE; 

} 

return (MRESULT)hDdf; 

} 

} 
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Initialize DDF Area 


#define INCL_DDF 


HDDF Ddflnitialize (HWND hwndHelpInstance, ULONG cbBuffer, ULONG ullncrement) 


This function initializes the IPF internal structures for dynamic data formatting and returns a DDF 
handle. The application uses this handle to refer to a particular DDF panel. 


Parameters 

hwndHelpInstance (HWND) - input 
Handle of a help instance. 
cbBuffer (ULONG) - input 

Initial length of internal buffer where DDF information is to be stored. If this field is NULL, a 
default value of IK is defined. The maximum value is 60KB. 

ullncrement (ULONG) - input 

Amount by which to increment the buffer size, if necessary. If this field is NULL, a default value 
of 256 bytes is defined. The maximum value is 60KB. 


Returns 

A handle to DDF (HDDF) is returned if initialization was successful. Otherwise, the value 
returned is: 

NULL An error has occurred because of insufficient memory or incorrect instance. 

Remarks 

At initialization, the default for dynamic data display is that text aligned on the left, and formatting is 
turned on. 

Related Functions 

• DdfText 

• DdfSetTextAlign 

• DdfSetFormat 

• DdfSetFontStyle 

• DdfSetFont 

• DdfSetColor 

• DdfPara 

• DdfMetafile 

• DdfListltem 

• Ddf Inform 

• Ddf HyperText 

• DdfEndList 

• DdfBitmap 

• DdfBeginList 

Example Code 

This example shows how to initialize and use the Dynamic Data Facility for displaying an online 
document. Two functions are defined: the first, SampleObj, creates a window that will display the 
online information and specifies the second function, SampleWindowProc, as the corresponding 
window procedure. These two functions are compiled into a DLL and exported, so that IPF can 
invoke them when it encounters the :ddf and :acviewport tags during execution. The :acviewport tag 
wilt specify the DLL name and the SampleObj function; when IPF calls SampleObj, it initializes an 
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Initialize DDF Area 


application-controlled window with SampleWindowProc as the window procedure and returns the 
window handle. Later, when IPF encounters the :ddf tag, it will send SampleWindowProc an 
HM_QUERY_DDF_DATA message. At this point, before calling any of the DDF API, Ddflnitialize must 
first be called to initiate a DDF buffer, after which the other DDF API can be called to display the 
online information. 

Idefine INCLJIINWINDOWMGR 
Idefine INCL_WINMESSAGEMGR 
Idefine INCL_WINDIALOGS 
Idefine I NCL_DDF 
Idefine INCL_32 
linclude <os2.h> 
linclude <pmhelp.h> 

Idefine C0M_HWND 4 
Idefine PAGE_HWND 8 
Idefine ACVP_HAB 12 

USHORT DdfClass = FALSE; 

MRESULT EXPENTRY SampleWindowProc (HWND hWnd, ULONG Message, 

MPARAM 1 Pa rami, MPARAM lParam2); 

USHORT API ENTRY Sampl eOb j ( PACVP pACVP, PCH Parameter) 

{ 

HWND DdfHwnd; /* Client window handle */ 

HWND DdfCHwnd; /* Child window handle */ 

HWND PreviousHwnd; /* Handle for setting comm window active */ 


/* General window management */ 
/* Message management */ 
/* Dialog boxes */ 
/* Dynamic Data Facility */ 


/* window word offsets */ 


/* register DDF Base class if not registered already */ 
if ( ! Ddf Cl ass) 

{ 

if (!WinRegisterClass( 

pACVP->hAB, /* Anchor block handle */ 

"CLASS_Ddf", /* Application window class name */ 

/* Address of window procedure */ 

SampleWindowProc, 

/* Window class style */ 

CS_SYNCPAINT | CSJIZEREDRAW | CS_M0VEN0TIFY, 

20)) /* Extra storage */ 

{ 

return TRUE; 

} 

DdfClass = TRUE; 

} 


/* create standard window */ 
if (! (DdfHwnd = WinCreateStdWindow( 

pACVP->hWndParent, /* ACVP is parent */ 
0L, /* No class style */ 
NULL, /* Frame control flag */ 


"CLASS_Ddf" , 
NULL, 

OL, 

OL, 

0 , 

&DdfCHwnd ))) 

{ 

return FALSE; 

} 

/* store the frame window handle 
pACVP->hWndACVP = DdfHwnd; 


/* Window class name */ 
/* No title bar */ 
/* No special style */ 
/* Resource in .EXE */ 
/* No window identifier */ 
/* Client window handle */ 


in ACVP data structure */ 
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/* set this window as active communication window */ 
PreviousHwnd = (HWND)WinSendMsg(pACVP->hWndParent, 

HM_SET 0BJC0M_WIND0W, 
MPFROMHWND(DdfHwnd) , NULL); 

/* save returned communication hwnd in reserved word */ 
WinSetWindowULong(DdfCHwnd, C0M_HWND, (ULONG) PreviousHwnd) ; 

/* save anchor block handle in reserved word */ 
WinSetWindowULong (DdfCHwnd, ACVP_HAB, (ULONG)pACVP->hAB) ; 

return FALSE; 

} /* SampleObj */ 


*/ 
*/ 
*/ 
*/ 

switch (Message) 

{ 

case HM_QUERY_DDF_DATA: 

Wi nSetWi ndowULong (hWnd , PAGE_HWND , LONGFROMMP ( 1 Paraml ) ) ; 

DdfID = LONGFROMMP (lParam2); 
hwndParent = WinQueryWindow(hWnd, QW_PARENT) ; 
hwndParent = WinQueryWindow(hwndParent, QW_PARENT); 
hwndlnstance = (HWND)WinSendMsg(hwndParent, HM QUERY, 

MPFROMSHORT(HMQW_INSTANCE) , NULL) ; 

/* Allocate IK Buffer (default) */ 
hDdf = Ddf Ini ti al i ze ( 

hwndlnstance, /* Handle of help instance */ 
OL, 

0L 

); 

if (hDdf = NULLHANDLE) 

{ 

return (MRESULT) FALSE; 

} 

return (MRESULT)hDdf; 
default: 

return (WinDefWindowProc(hWnd, Message, 1 Paraml, lParam2)); 

} 

} /* SampleWindowProc */ 


/* Default buffer size */ 

/* Default increment */ 

/* Check return code */ 


MRESULT EXPENTRY SampleWindowProc (HWND hWnd, ULONG Message, 


{ 


HWND hwndParent ; 
HWND hwndlnstance; 
HDDF hDdf; 

ULONG DdfID; 


MPARAM 1 Paraml, MPARAM lParam2) 

/* parent window 
/* help instance window 
/* DDF handle 
/* DDF resource id 
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Insert List Item 


#define INCL_DDF 


BOOL OdfListllem (HDDF hddf, PSZ pszTerm, PSZ pszDescrlption) 


This function inserts a definition list entry in the DDF buffer; it corresponds to a combination of the 
:dt. (definition term) and :dd. (definition define) tags. 

Parameters 

hddf (HDDF) - input 

Handle to DDF returned by Ddflnitialize. 
pszTerm (PSZ) - input 

Term portion of the definition list entry. 
pszDescription (PSZ) - input 

Description portion of the definition list entry. 


Returns 

Success indicator. 

TRUE Successful completion. 

FALSE Error occurred. 

Possible returns from WinGetLastError 

HMERR DDF MEMORY Not enough memory is available. 

H M E R R DDF LIST U NINITIALIZED No definition list has been initialized by DdfBeginList. 

Remarks 

The handle to the presentation space in which the bit map was created cannot be freed by the 
application while the panel is displayed. 

Note: There is a (3-byte + size of HBITMAP structure) ESC code overhead in the DDF internal buffer 
for this function. There is a 1-byte ESC code overhead required for the Align flag. 


Related Functions 

• DdfText 

• DdfSetTextAlign 

• DdfSetFormat 

• DdfSetFontStyle 

• DdfSetFont 

• DdfSetColor 

• DdfPara 

• DdfMetafile 

• Ddflnitialize 

• Ddflnform 

• Ddf HyperText 

• DdfEndList 

• DdfBitmap 

• DdfBeginList 
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Insert List Item 


Example Code 

After initializing a DOF buffer with Ddflnitialize, the example uses DdfBeginList to indicate the 
beginning of a definition list in the DDF buffer (this corresponds to the IPF dl tag). For a more 
detailed example and discussion of initializing DDF, see the Ddflnitialize sample. 


Idefine INCL_WINWINDOWMGR /* General window management */ 

Idefine INCL_WINMESSAGEMGR /* Message management */ 

Idefine INCL_DDF /* Dynamic Data Facility */ 

linclude <os2.h> 
linclude <pmhelp.h> 

struct _LISTITEM /* definition list */ 

{ 

PSZ Term; 

PSZ Desc; 

} Definition [2] = {{"MVS", "Multiple Virtual 
System"}, 

{"VM", "Virtual Machine"}}; 

MRESULT WindowProc( HWND hwnd, ULONG ulMsg, MPARAM mpl, MPARAM mp2) 

{ 

HWND hwndParent; 

HWND hwndlnstance; 

HDDF hDdf; /* DDF handle */ 

SHORT i; /* loop index */ 

switch( ulMsg ) 

{ 

case HM_QUERY_DDF_DATA : 

/* get the help instance */ 
hwndParent = WinQueryWindow( hwnd, QW_PARENT ); 
hwndParent = WinQueryWindow( hwndParent, QW_PARENT ); 
hwndlnstance = (HWND)WinSendMsg( hwndParent, HM_QUERY, 

MPFR0MSH0RT( HMQW_INSTANCE ), NULL ); 


/* Allocate IK Buffer (default) */ 
hDdf = Ddf Ini ti al i ze ( 

hwndlnstance, /* Handle of help instance */ 
0L, /* Default buffer size */ 
0L /* Default increment */ 
); 


if (hDdf == NULLHANDLE) /* Check return, code */ 

{ 

return (MRESULT)FALSE; 

} 


/* begin definition list */ 

if ( ! DdfBegi nLi s t (hDdf , 3L, HMBT_ALL, HMLS_SINGLELINE) ) 

{ 

return (MRESULT)FALSE; 

} 
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/* insert 2 entries into definition list */ 
for ( i =0; i < 2; i++) 

{ 

if (!DdfListItem(hDdf, Definition^] .Term, 
Definition[i].Desc)) 

{ 

return (MRESULT) FALSE; 

} 

} 

/* terminate definition list */ 
if ( ! Ddf EndLi st (hDdf ) ) 

{ 

return (MRESULT) FALSE; 

} 

return (MRESULT)hDdf; 

} 

} 
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DdfMetafile - 
Place Metafile Reference 


#define INCL_DDF 


BOOL DdIMelallle (HDDF hddf, HMF hmf, PRECTL prcIRect) 


This function places a reference to a metafile into the DDF buffer. 

Parameters 

hddf (HDDF) - input 

Handle to DDF returned by Ddflnitialize. 
hmf (HMF) - input 

The handle of the metafile to display. 
prcIRect (PRECTL) - input 

If not NULL, contains the size of the rectangle in which the metafile will be displayed. The 
aspect ratio of the metafile is adjusted to fit this rectangle. 


Returns 

Success indicator. 

TRUE Successful completion. 

FALSE Error occurred. 

Possible returns from WinGetLastError 

HMERRDDFMEMORY Not enough memory is available. 

Remarks 

Note: There is a 3-byte ESC code overhead in the DDF internal buffer for this function. There is also 
a (MetaFilename length) overhead. Finally, the Rect variable requires an additional 16 bytes 
of overhead in the DDF internal buffer. 

Related Functions 

• DdfText 

• DdfSetTextAlign 

• DdfSetFormat 

• DdfSetFontStyle 

• DdfSetFont 

• DdfSetColor 

• DdfPara 

• DdfListltem 
■ Ddflnitialize 

• Ddflnform 

• Ddf HyperText 

• DdfEndList 

• DdfBitmap 

• DdfBeginList 
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DdfMetafile - 

Place Metafile Reference 


Example Code 


After initializing a DDF buffer with Ddf Initialize and loading a metafile with GpiLoadMetaFile, the 
example uses DdfMetafile to place a reference to the metafile in the DDF buffer. For a more detailed 
example and discussion of initializing DDF, see the Ddflnitialize sample. 


Idefine INCLJIINWINDOWMGR 
Idefine INCL_WINMESSAGEMGR 
Idefine INCL_DDF 
Idefine INCL_GPIMETAFILES 
linclude <os2.h> 
linclude <pmhelp.h> 


/* General window management */ 
/* Message management */ 
/* Dynamic Data Facility */ 
/* MetaFiles */ 


Idefine MF_HWND 0 
Idefine ACVP_HAB 4 


MRESULT WindowProc( HWND hwnd, ULONG ulMsg, MPARAM mpl, MPARAM mp2 ) 

{ 

HWND hwndParent; 

HAB hab; 

HWND hwndlnstance; /* help instance window */ 

HDDF hDdf; /* DDF handle */ 

HMF hwndMetaFile; /* metafile handle */ 

switch( ulMsg ) 

{ 

case HM_QUER Y_DD F DAT A : 

/* get the help instance */ 
hwndParent = WinQueryWindow( hwnd, QW_PARENT ); 
hwndParent = WinQueryWindow( hwndParent, QWPARENT ); 
hwndlnstance = (HWND)WinSendMsg( hwndParent, HM QUERY, 

MPFR0MSH0RT( HMQWINSTANCE ), NULL ); 


/‘Allocate IK Buffer (default) */ 
hDdf = Ddf Ini t ial i ze( 

hwndlnstance, /‘Handle of help instance */ 

0L, /* Default buffer size */ 

0L /* Default increment */ 

); 

if (hDdf = tfULLHANDLE) /* Check return code */ 

{ 

return (MRESULT) FALSE; 

} 

/* get hab for this window */ 

if ((hab = (HAB)WinQueryWindowULong(hwnd, ACVP_HAB)) == NULLHANDLE) 

{ 

return (MRESULT) FALSE; 

} 

/‘ Load the Metafile to display */ 

if ((hwndMetaFile = GpiLoadMetaFile(hab, "SAMP. MET")) == NULLHANDLE) 

{ 

return (MRESULT) FALSE; 

} 
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/* Save MetaFile hwnd in reserved word */ 
WinSetWindowULong(hwnd, MFHWND, hwndMetaFile) ; 

if (!DdfMetafi1e(hDdf, hwndMetaFile, NULL)) 

{ 

return (MRESULT) FALSE; 

} 

return (hDdf); 
case WM_CL0SE: 

Gpi Del eteMetaFi 1 e ( (HMF)Wi nQueryWi ndowULong ( hwnd , MF_HWND) ) ; 
WinDestroyWindow(WinQueryWindow(hwnd, QW PARENT) ) ; 

return (MRESULT)TRUE; 

} 

return WinDefWindowProc( hwnd, ulMsg, mpl, mp2 ); 
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Create a Paragraph in DDF Buffer 


#define INCL_DDF 


BOOL DdfPara (HDDF hddf) 


This function creates a paragraph within the DDF buffer. It corresponds to the :p. tag. This function 
places a reference to a bit map in the DDF buffer. 

Parameters 

hddf (HDDF) - input 

Handle to DDF returned by Ddflnitialize. 


Returns 

Success indicator. 

TRUE Successful completion. 

FALSE Error occurred. 

Possible returns from WinGetLastError 

HMERR DDF MEMORY Not enough memory is available. 

Remarks 

Note: There is a 1-byte ESC code overhead in the DDF internal buffer for this function. 

Related Functions 

• DdfText 

• DdfSetTextAlign 

• DdfSetFormat 

• DdfSetFontStyle 

• DdfSetFont 

• DdfSetColor 

• DdfMetafile 

• DdfListltem 

• Ddflnitialize 

• Ddflnform 

• Ddf HyperText 

• DdfEndList 

• DdfBitmap 

• DdfBeginList 

Example Code 

After initializing a DDF buffer with Ddflnitialize, the example uses DdfPara to start a new paragraph, 
DdfSetFont and DdfSetFontStyle to have the text displayed in a large, bold Courier font, DdfSetColor 
to change the text color, and DdfText to place text in the buffer. For a more detailed example and 
discussion of initializing DDF, seethe Ddflnitialize sample. 

Idefine INCLJIINWINDOWMGR /* General window management */ 

Idefine INCL_WINMESSAGEMGR /* Message management */ 

#define INCL_DDF /* Dynamic Data Facility */ 

linclude <os2.h> 
linclude <pmhelp.h> 
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Create a Paragraph in DDF Buffer 


MRESULT WindowProc( HWND hwnd, ULONG ulMsg, MPARAM mpl, MPARAM mp2 ) 
{ 


HWND 

hwndParent; 



HWND 

hwndlnstance; 

/* help instance window 

*/ 

HDDF 

hDdf; 

/* DDF handle 

*/ 


switch( ulMsg ) 

{ 

case HM_Q U E R Y_DDF_DAT A : 

/* get the help instance */ 
hwndParent = WinQueryWindow( hwnd, QW_PARENT ); 
hwndParent = WinQueryWindow( hwndParent, QW_PARENT ); 
hwndlnstance = (HWND)WinSendMsg( hwndParent, HMQUERY, 

MPFROMSHORT( HMQW_INSTANCE ), NULL ); 

/* Allocate IK Buffer (default) */ 
hDdf = Ddflnitial ize( 

hwndlnstance, /* Handle of help instance */ 

0L, /* Default buffer size */ 

0L /* Default increment */ 

); 

if (hDdf = NULLHANDLE) /* Check return code */ 

{ 

return (MRESULT) FALSE; 

} 

/* create paragraph in DDF buffer */ 
if( ! DdfPara ( hDdf ) ) 

{ 

return (MRESULT) FALSE; 

} 

/* Change to large (100 x 100 dimensions) Courier font */ 
if( !DdfSetFont( hDdf, "Courier", 10OL, 100L ) ) 

{ 

return (MRESULT)FALSE; 

} 

/* make the font BOLDFACE */ 

if ( !DdfSetFontStyle( hDdf, FM_SEL_B0LD ) ) 

{ 

return (MRESULT) FALSE; 

} 

/* make the text display as BLUE on a PALE GRAY background */ 
if( !DdfSetColor( hDdf, CLR_PALEGRAY, CLR_BLUE ) ) 

{ 

return (MRESULT) FALSE; 

} 

/* Write data into the buffer */ 
if (!DdfText(hDdf, "Sample Text")) 

{ 

return (MRESULT) FALSE; 

} 

return (MRESULT ) hDdf; 

} 

return WinDefWindowProc( hwnd, ulMsg, mpl, mp2 ); 
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Set Color of Text 


#define INCL_DDF 


BOOL DdfSetColor (HOOF hddf, COLOR BackColor, COLOR ForColor) 


This function sets the background and foreground colors of the displayed text. 


Parameters 

hddf (HDDF) - input 

Handle to DDF returned by Ddflnitialize. 

BackColor (COLOR) - input 

Specifies the desired background color. 

ForColor (COLOR) - input 

Specifies the desired foreground color. 

The following color value constants may be used for the foreground and background colors: 

CLR_DEFAULT - used to set IPF default text color 

CLR_BLACK 

CLR_BLUE 

CLR_RED 

CLR_PINK 

CLR_GREEN 

CLR_CYAN 

CLR_YELLOW 

CLR_BROWN 

CLR_DARKGRAY 

CLR_DARKBLUE 

CLR_DARKRED 

CLR_DARKPINK 

CLR_DARKGREEN 

CLR_DARKCYAN 

CLR_PALEGRAY 

CLR_UNCHANGED 


Returns 

Success indicator. 

TRUE Successful completion. 

FALSE Error occurred. 

Not enough memory is available. 
The background color is not valid. 
The foreground color is not valid. 


Possible returns from WinGetLastError 

HMERR_DDF MEMORY 

HMERRDDFBACKCOLOR 

HMERRDDFFORCOLOR 
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Set Color of Text 


Remarks 

Note: There is a 4-byte ESC code overhead in the DDF internal buffer for the foreground color, and a 
4-byte overhead for the background color, with this function. 


Related Functions 

• DdfText 

• DdfSetTextAlign 

• DdfSetFormat 

• DdfSetFontStyle 

• DdfSetFont 

• DdfPara 

• DdfMetafile 

• DdfListltem 

• Ddflnitialize 

• Ddflnform 

• DdfHyperText 

• DdfEndList 

• Ddf Bitmap 

• DdfBeginList 


Example Code 

After initializing a DDF buffer with Ddflnitialize, the example uses DdfPara to start a new paragraph, 
DdfSetFont and DdfSetFontStyle to have the text displayed in a large, bold Courier font, DdfSetColor 
to change the text color, and DdfText to place text in the buffer. For a more detailed example and 
discussion of initializing DDF, see the Ddflnitialize sample. 

#define INCL_WINWINDOWMGR /* General window management */ 

Idefine INCL_WINMESSAGEMGR /* Message management */ 

fdefine INCL_DDF /* Dynamic Data Facility */ 

finclude <os2.h> 
linclude <pmhelp.h> 


MRESULT WindowProc( HWND hwnd, ULONG ulMsg, 

{ 

HWND hwndParent; 

HWND hwndlnstance; /* help instance 

HDDF hDdf; /* DDF handle 


MPARAM mpl, MPARAM mp2 ) 


wi ndow 


*/ 

*/ 


switch ( ulMsg ) 

{ 

case HM_QUERY_DDF_DATA : 

/* get the help instance */ 
hwndParent = WinQueryWindow( hwnd, QW_PARENT ); 
hwndParent = WinQueryWindow( hwndParent, QW_PARENT ); 
hwndlnstance = (HWND)WinSendMsg( hwndParent, HM QUERY, 

MPFR0MSH0RT( HMQW_INSTANCE ), NULL ); 


/* Allocate IK Buffer (default) */ 


hDdf = Ddflnitial ize( 

hwndlnstance, 

OL, 

0L 

); 


/* Handle of help instance */ 
/* Default buffer size */ 
/* Default increment */ 


if (hDdf == NULLHANDLE) /* Check return code */ 

{ 

return (MRESULT)FALSE; 

} 
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/* create paragraph in DDF buffer */ 
if( !DdfPara( hDdf ) ) 

{ 

return (MRESULT) FALSE; 

} 

/* Change to large (100 x 100 dimensions) Courier font */ 
if( !DdfSetFont( hDdf, "Courier", 10OL, 10OL ) ) 

{ 

return (MRESULT) FALSE; 

} 

/* make the font BOLDFACE */ 

if( !DdfSetFontStyle( hDdf, FM_SEL_BOLD ) ) 

{ 

return (MRESULT) FALSE; 

} 

/* make the text display as BLUE on a PALE GRAY background */ 
if( !DdfSetColor( hDdf, CLRPALEGRAY, CLR_BLUE ) ) 

{ 

return (MRESULT) FALSE; 

} 

/* Write data into the buffer */ 
if (!DdfText(hDdf, "Sample Text")) 

{ 

return (MRESULT) FALSE; 

} 

return (MRESULT)hDdf; 

} 

return WinDefWindowProc( hwnd, ulMsg, mpl, mp2 ); 
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Specify Text Font 


#define INCL_DDF 


BOOL DdfSetFont (HDDF hddf, PSZ pszFaceName, ULONG ulWIdth, ULONG ulHelght) 


This function specifies a text font in the DDF buffer. 

Parameters 

hddf (HDDF) - input 

Handle to DDF returned by Ddflnitialize. 

pszFaceName (PSZ) - input 

This parameter can be specified in two ways: 

An ASCIIZ string specifying the font name. 

"NULL” or “DEFAULT” to specify the default font. 

ui Width (ULONG) - input 

Font width in in points. A point is approximately 1/72 of an inch 
ulHelght (ULONG) - input 
Font height in points. 


Returns 

Success indicator. 

TRUE Successful completion. 

FALSE Error occurred. 

Possible returns from WinGetLastError 

HMERRDDFMEMORY Not enough memory is available. 

Related Functions 

• DdfText 

• DdfSetTextAlign 

• DdfSetFormat 

• DdfSetFontStyle 

• DdfSetColor 

• DdfPara 

• DdfMetafile 

• DdfListltem 

• Ddflnitialize 

• Ddflnform 

• Ddf HyperText 

• DdfEndList 

• DdfBitmap 

• DdfBeginList 
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DdfSetFont - 
Specify Text Font 


Example Code 

After initializing a DDF buffer with Ddflnitialize, the example uses DdfPara to start a new paragraph, 
DdfSetFont and DdfSetFontStyle to have the text displayed in a large, bold Courier font, DdfSetColor 
to change the text color, and DdfText to place text in the buffer. For a more detailed example and 
discussion of initializing DDF, see the Ddflnitialize sample. 

Idefine INCL_WINWINDOWMGR /* General window management */ 

Idefine INCL_WINMESSAGEMGR /* Message management */ 

Idefine INCL_DDF /* Dynamic Data Facility */ 

linclude <os2.h> 
linclude <pmhelp.h> 


MRESULT WindowProc( HWND hwnd, ULONG ulMsg, MPARAM mpl, MPARAM mp2 ) 

{ 

HWND hwndParent ; 

HWND hwndlnstance; /* help instance window */ 

HDDF hDdf; /* DDF handle */ 

switch( ulMsg ) 

{ 

case HM_QUERY_DDF_DATA : 

/* get the help instance */ 
hwndParent = WinQueryWindow( hwnd, QW_PARENT ); 
hwndParent = WinQueryWindow( hwndParent, QW PARENT ); 
hwndlnstance = (HWND)WinSendMsg( hwndParent, HM_QUERY, 

MPFROMSHORK HMQW INSTANCE ), NULL ); 

/* Allocate IK Buffer (default) */ 
hDdf = Ddflnitial ize( 

hwndlnstance, /* Handle of help instance */ 

OL, /* Default buffer size */ 

0L /* Default increment */ 

); 

if (hDdf == NULLHANDLE) /* Check return code */ 

{ 

return (MRESULT) FALSE; 

} 

/* create paragraph in DDF buffer */ 
if( ! DdfPara ( hDdf ) ) 

{ 

return (MRESULT) FALSE;. 

} 

/* Change to large (100 x 100 dimensions) Courier font */ 
if( ! DdfSetFont ( hDdf, "Courier", 100L, 100L ) ) 

{ 

return (MRESULT) FALSE; 

} 

/* make the font BOLDFACE */ 

if( !DdfSetFontStyle( hDdf, FM_SEL_B0LD ) ) 

{ 

return (MRESULT) FALSE; 

} 
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/* make the text display as BLUE on a PALE GRAY background */ 
if( !DdfSetColor( hDdf, CLR_PALEGRAY, CLR_BLUE ) ) 

{ 

return (MRESULT) FALSE; 

} 

/* Write data into the buffer */ 
if (!DdfText(hDdf, "Sample Text")) 

{ 

return (MRESULT) FALSE; 

} 

return (MRESULT) hDdf; 

} 

return WinDefWindowProc( hwnd, ulMsg, mpl, mp2 ); 
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Specify Text Font Style 


#define INCL_DDF 


BOOL DdfSetFontStyle (HODF hddf, ULONG (FontStyle) 


This function specifies a text font style in the DDF buffer. 


Parameters 

hddf (HDDF) - input 

Handle to DDF returned by Ddflnitialize. 
fFontStyle (ULONG) - input 

A NULL value for this parameter will set the font-style back to the default. Any of the following 
values can be specified: 

FM_SEL_ITALIC 

FM_SEL_BOLD 

FM_SEL_UNDERSCORE 

These values can be “ORed” together to combine different font styles. 

Note: There is a 4-byte ESC code overhead in the DDF internal buffer for FontStyle. 

Returns 

Success indicator. 

TRUE Successful completion. 

FALSE Error occurred. 

Possible returns from WinGetLastError 

HMERRDDFMEMORY 
HMERR_DDF_FONTSTYLE 

Related Functions 

• DdfText 

• DdfSetTextAlign 

• DdfSetFormat 

• DdfSetFont 

• DdfSetColor 

• DdfPara 

• DdfMetafile 

• DdfListltem 

• Ddflnitialize 

• Ddflnform 

• Ddf HyperText 

• DdfEndList 

• DdfBitmap 

• DdfBeginList 


Not enough memory is available. 
The font style is not valid. 
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Specify Text Font Style 


Example Code 

After initializing a DDF buffer with Ddflnitialize, the example uses DdfPara to start a new paragraph, 
DdfSetFont and DdfSetFontStyle to have the text displayed in a large, bold Courier font, DdfSetColor 
to change the text color, and DdfText to place text in the buffer. For a more detailed example and 
discussion of initializing DDF, seethe Ddflnitialize sample. 

Idefine INCL_WINWINDOWMGR /* General window management */ 

Idefine INCL_WINMESSAGEMGR /* Message management */ 

Idefine INCL_DDF /* Dynamic Data Facility */ 

linclude <os2.h> 
linclude <pmhelp.h> 


MRESULT WindowProc( HWND hwnd, ULONG ulMsg, MPARAM mpl, MPARAM mp2 ) 
{ 


HWND 

hwndParent ; 



HWND 

hwndlnstance; 

/* help instance window 

*/ 

HDDF 

hDdf; 

/* DDF handle 

*/ 


switch( ulMsg ) 

{ 

case HM_QUERY_DD F DAT A : 

/* get the help instance */ 
hwndParent = WinQueryWindow( hwnd, QWPARENT ); 
hwndParent = WinQueryWindow( hwndParent, QW PARENT ); 
hwndlnstance = (HWND)WinSendMsg( hwndParent, HM QUERY, 

MPFROMSHORT ( HMQW_INSTANCE ), NULL ); 

/* Allocate IK Buffer (default) */ 
hDdf = Ddflnitialize( 

hwndlnstance, /* Handle of help instance */ 

0L, /* Default buffer size */ 

0L /* Default increment */ 

); 

if (hDdf == NULLHANDLE) /* Check return code */ 

{ 

return (MRESULT) FALSE; 

} 

/* create paragraph in DDF buffer */ 
if ( ! DdfPara ( hDdf ) ) 

{ 

return (MRESULT) FALSE; 

} 

/* Change to large (100 x 100 dimensions) Courier font */ 
if( !DdfSetFont( hDdf, "Courier", IDOL, 100L ) ) 

{ 

return (MRESULT) FALSE; 

} 

/* make the font BOLDFACE */ 

if( !DdfSetFontStyle( hDdf, FM_SEL_B0LD ) ) 

{ 

return (MRESULT) FALSE; 

} 
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/* make the text display as BLUE on a PALE GRAY background */ 
if( IDdfSetColor( hDdf, CLR_PALEGRAY, CLR_BLUE ) ) 

{ 

return (MRESULT) FALSE; 

} 

/* Write data into the buffer */ 
if ( ! Ddf Text (hDdf, "Sample Text")) 

{ 

return (MRESULT) FALSE; 

} 

return (MRESULT) hDdf; 

} 

return WinDefWindowProc( hwnd, ulMsg, mpl, mp2 ); 

} 
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Control Formatting 


#define INCL DDF 


BOOL DdfSetFormat (HDDF hddf, ULONG fFormatType) 


This function is used to turn formatting off or on. It corresponds to the dines, tag. 


Parameters 

hddf (HDDF) - input 

Handle to DDF returned by Ddflnitialize. 

fFormatType (ULONG) - input 

Only the following constants may be used in this parameter: 

TRUE Turn formatting on. 

FALSE Turn formatting off. 

Returns 

Success indicator. 

TRUE Successful completion. 

FALSE Error occurred. 

Possible returns from WinGetLastError 

HMERR_DDF MEMORY Not enough memory is available. 

Remarks 

Note: If formatting is ON, there is a 3-byte ESC code overhead in the DDF internal buffer for this 
function. Otherwise, there is a 4-byte ESC code overhead. 


Related Functions 

• DdfText 

• DdfSetTextAlign 

• DdfSetFontStyle 

• DdfSetFont 

• DdfSetColor 

• DdfPara 

• DdfMetafile 

• DdfListltem 

• Ddflnitialize 

• Ddf Inform 

• DdfHyperText 

• DdfEndList 

• DdfBitmap 

• DdfBeginList 
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Control Formatting 


Example Code 

After initializing a DDF buffer with Ddflnitialize, the example uses DdfSetTextAlign to specify left 
justified test in the DDF buffer when formatting is OFF. The example then uses DdfSetFormat to turn 
off formatting for text in the DDF buffer (corresponds to the IPF lines tag). For a more detailed 
example and discussion of initializing DDF, see the Ddflnitialize sample. 


Idefine INCL_WINWINDOWMGR 
Idefine INCL_WINMESSAGEMGR 
Idefine INCL_GPIPRIMITIVES 
Idefine INCL_DDF 
linclude <os2.h> 
linclude <pmhelp.h> 


/* General window management */ 
/* Message management */ 
/* Drawing Primitives/Attributes*/ 
/* Dynamic Data Facility */ 


MRESULT WindowProc( HWND hwnd, ULONG ulMsg, MPARAM mpl, MPARAM mp2 ) 
{ 


HWND 

hwndParent; 



HWND 

hwndlnstance; 

/* help instance window 

*/ 

HDDF 

hDdf; 

/* DDF handle 

*/ 


switch( ulMsg ) 

{ 

case HM_QUERY_DDF_DATA: 

/* get the help instance */ 
hwndParent = WinQueryWindow( hwnd, QWPARENT ); 
hwndParent = WinQueryWindow( hwndParent, QW_PARENT ); 
hwndlnstance = (HWND)WinSendMsg( hwndParent, HM_QUERY, 

MPFR0MSH0RT( HMQWINSTANCE ), NULL ); 


/* Allocate IK Buffer (default) */ 


hDdf = Ddflnitial ize( 

hwndlnstance, 

0L, 

0L 

); 


/* Handle of help instance */ 
/* Default buffer size */ 
/* Default increment */ 


if (hDdf == NULLHANDLE) /* Check return code */ 

{ 

return (MRESULT)FALSE; 

} 


/* left justify text when formatting is OFF */ 
if (! DdfSetTextAlign (hDdf, TA_LEFT)) 

{ 

return (MRESULT) FALSE; 

} 


/* turn formatting OFF */ 
if (!DdfSetFormat(hDdf, FALSE)) 

{ 

return (MRESULT) FALSE; 

} 

if (!DdfText(hDdf, 

"Format OFF: This text should be Left A1 igned!\n")) 

{ 

return (MRESULT) FALSE; 

} 


return (MRESULT) hDdf; 

} 

return WinDefWindowProc( hwnd, ulMsg, mpl, mp2 ); 
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DdfSetTextAlign - 
Define Text Alignment 


#define INCL DDF 


BOOL DdfSetTextAlign (HDDF hddf, ULONG fAIIgn) 


This function defines whether left, center, or right text justification is to be used when text formatting 
is off. 

Parameters 

hddf (HDDF) - input 

Handle to DDF returned by Ddflnitialize. 

fAIIgn (ULONG) - input 

Only the following constants may be used: 

TA_LEFT Left-justify text. 

TA_RIGHT Right-justify text. 

TA_CENTER Center text. 

Returns 

Success indicator. 

TRUE Successful completion. 

FALSE Error occurred. 

Possible returns from WinGetLastError 

HMERR_DDF_ALIGN_TYPE The alignment type is not valid. 

Remarks 

It should be called before DdfSetFormat is called to turn off text formatting, and should not be called 
again until formatting is turned back on. Note that leading and trailing spaces are not stripped from 
the text as a result of this alignment. 


Related Functions 

• DdfText 

• DdfSetFormat 

• DdfSetFontStyle 

• DdfSetFont 

• DdfSetColor 

• DdfPara 

• DdfMetafile 

• DdfListltem 

• Ddflnitialize 

• Ddflnform 

• DdfHyperText 

• DdfEndList 

• DdfBitmap 

• DdfBeginList 
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DdfSetTextAlign - 
Define Text Alignment 


Example Code 

After initializing a DDF buffer with Ddflnitialize, the example uses DdfSetTextAlign to specify left 
justified test in the DDF buffer when formatting is OFF. The example then uses DdfSetFormat to turn 
off formatting for text in the DDF buffer (corresponds to the IPF lines tag). For a more detailed 
example and discussion of initializing DDF, see the Ddflnitialize sample. 


Idefine INCL_WINWINDOWMGR 
Idefine INCL_WINMESSAGEMGR 
Idefine INCL_GPI PRIMITIVES 
Idefine INCL_DDF 
linclude <os2.h> 
linclude <pmhelp.h> 


/* General window management */ 
/* Message management */ 
/* Drawing Primitives/Attributes*/ 
/* Dynamic Data Facility */ 


MRESULT Wi ndowProc( HWND hwnd, ULONG ulMsg, MPARAM mpl, MPARAM mp2 ) 
{ 


HWND 

hwndParent; 



HWND 

hwndlnstance; 

/* help instance window 

*/ 

HDDF 

hDdf; 

/* DDF handle 

*/ 


switch ( ulMsg ) 

{ 

case HM_QU E R Y_DD FDAT A : 

/* get the help instance */ 
hwndParent = WinQueryWindow( hwnd, QWPARENT ); 
hwndParent = WinQueryWindow( hwndParent, QW_PARENT ); 
hwndlnstance = (HWND)WinSendMsg( hwndParent, HM_QUERY, 

MPFROMSHORT ( HMQWINSTANCE ), NULL ); 


/* Allocate IK Buffer (default) */ 


hDdf = Ddflnitialize( 

hwndlnstance, 

OL, 

0L 

); 


/* Handle of help instance */ 
/* Default buffer size */ 
/* Default increment */ 


if (hDdf == NULLHANDLE) /* Check return code */ 

{ 

return (MRESULT) FALSE; 

} 


/* left justify text when formatting is OFF */ 
if (! DdfSetTextAlign (hDdf, TA_LEFT)) 

{ 

return (MRESULT) FALSE; 

} 


/* turn formatting OFF */ 
if ( IDdfSetFormat (hDdf , FALSE)) 
{ 

return (MRESULT) FALSE; 

} 


if (!DdfText(hDdf, 

"Format OFF: This text should be Left Aligned!\n")) 

{ 

return (MRESULT) FALSE; 

} 


return (MRESULT) hDdf; 

} 

return WinDefWindowProc( hwnd, ulMsg, mpl, mp2 ); 
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DdfText - 

Add Text to DDF Buffer 


#define INCL_DDF 


BOOL DdfText (HDDF hddf, PSZ pszText) 


This function adds text to the DDF buffer. 

Parameters 

hddf (HDDF) - input 

Handle to DDF returned by Ddflnitialize. 
pszText (PSZ) - input 

Pointer to the text buffer to be formatted. 

Note: There is a 3-byte ESC code overhead in the DDF internal buffer for each word in the text 
buffer. There is a 1-byte ESC code overhead for each blank and for each newline 
character. 

Returns 

Success indicator. 

TRUE Successful completion. 

FALSE Error occurred. 

Related Functions 

• DdfSetTextAlign 

• DdfSetFormat 

• DdfSetFontStyle 

• DdfSetFont 

• DdfSetColor 

• DdfPara 

• Ddf Metafile 

• DdfListltem 

• Ddflnitialize 

• Ddf Inform 

• Ddf HyperText 

• DdfEndList 

• DdfBitmap 

• DdfBeginList 

Example Code 

After initializing a DDF buffer with Ddflnitialize, the example uses DdfPara to start a new paragraph, 
DdfSetFont and DdfSetFontStyle to have the text displayed in a large, bold Courier font, DdfSetColor 
to change the text color, and DdfText to place text in the buffer. For a more detailed example and 
discussion of initializing DDF, see the Ddflnitialize sample. 

Idefine INCL_WINWINDOWMGR /* General window management */ 

Idefine INCL_WINMESSAGEMGR /* Message management */ 

Idefine INCL_DDF /* Dynamic Data Facility */ 

linclude <os2.h> 
linclude <pmhelp.h> 


MRESULT WindowProc( HWND hwnd, ULONG ulMsg, MPARAM mpl, MPARAM mp2 ) 

{ 
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DdfText - 

Add Text to DDF Buffer 


HWND 

hwndParent; 



HWND 

hwndlnstance; 

/* help instance window 

*/ 

HDDF 

hDdf; 

/* DDF handle 

*/ 


switch( ulMsg ) 

{ 

case HM_QUERY_DDF_DATA : 

/* get the help instance */ 
hwndParent = WinQueryWindow( hwnd, QWPARENT ); 
hwndParent = WinQueryWindow( hwndParent, QW PARENT ); 
hwndlnstance = (HWND)WinSendMsg( hwndParent, HMQUERY, 

MPFR0MSH0RT( HMQWINSTANCE ), NULL ); 


/* Allocate IK Buffer (default) */ 


hDdf = Ddflnitial ize( 

hwndlnstance, 

OL, 

OL 

); 


/* Handle of help instance */ 
/* Default buffer size */ 
/* Default increment */ 


if (hDdf == NULLHANDLE) /* Check return code */ 

{ 

return (MRESULT) FALSE; 

} 


/* create paragraph in DDF buffer */ 
if ( !DdfPara( hDdf ) ) 

{ 

return (MRESULT) FALSE; 

} 

/* Change to large (100 x 100 dimensions) Courier font */ 
if ( !DdfSetFont( hDdf, "Courier", 100L, 100L ) ) 

{ 

return (MRESULT) FALSE; 

} 


/* make the font BOLDFACE */ 

if ( !DdfSetFontStyle( hDdf, FM_SEL_B0LD ) ) 

{ 

return (MRESULT) FALSE; 

} 

/* make the text display as BLUE on a PALE GRAY background */ 
if( !DdfSetColor( hDdf, CLR_PALEGRAY , CLR_BLUE ) ) 

{ 

return (MRESULT) FALSE; 

} 

/* Write data into the buffer */ 
if (! DdfText (hDdf , "Sample Text")) 

{ 

return (MRESULT) FALSE; 

} 

return (MRESULT)hDdf; 

} 

return WinDefWindowProc( hwnd, ulMsg, mpl, mp2 ); 
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Chapter 5. Graphics Functions 


Coordinates 

GPI coordinate values that are in world or model space are passed in variables of data type LONG. 
For a presentation space of format GPIF_LONG (see GpiCreatePS), the signed value must be 
contained within the low-order 28 bits. 

For a presentation space with a format of GPIF_SHORT, the signed value must be contained within 
the low-order 16 bits. Coordinates that exceed this limit are truncated without error, when stored in 
a segment. As a consequence, a large positive number may appear as a negative number. 

In both instances, after transformation to media space (that is, device space, possibly including a 
translation for the window origin), coordinate values must be in the range —32 768 through +32 767. 

The PMERR_COORDINATE_OVERFLOW error condition occurs if a coordinate is too large to be 
handled. 

Region coordinates must be within the range —32 767 through +32 765. 


Matrix Parameter Values 

These GPI functions define transforms: 

• GpiSetSegmentTransformMatrix 

• GpiSetModelTransformMatrix 

• GpiCallSegmentMatrix 

• GpiSetViewingTransformMatrix 

• GpiSetDefauItViewMatrix 

• GpiCreatePS 

• GpiSetPageViewport. 

Note: The last two functions define the device transform; the page viewport may be defaulted. 

Concatenation of transform matrixes can occur as the transform is specified, for example, if 
TRANSFORM_ADD is specified. Concatenation also occurs during drawing, between the various 
transforms in the viewing pipeline. 

During the process of concatenation, it is possible for the matrix parameter overflow error, 
PMERR_INV_MATRIX_ELEMENT, to occur. This error is raised if either of the following conditions 
occurs for any intermediate value during the concatenation arithmetic (see, for example, 
GpiSetSegmentTransformMatrix for an explanation of matrix element numbers): 

• Any of the matrix elements 1, 2, 4, or 5 is greater than 32 767 or less than —32 768 (+1 for a 
GPIF_SHORT format presentation space), or 

• Either of elements 7 or 8 is greater than 134 217 727 (227 _i) or less than —134 217 728 (—227) 
(greater than 32 767 or less than —32 768 for a GPIF SHORT format presentation space). 


Rounding Errors 

In general for graphics coordinates, when non-unity transforms (apart from simple translation) are 
involved, rounding errors occur. For example, adding the coordinates of one point to a delta value, 
to produce the coordinates of a second point (all in world coordinates) does not always map to the 
same device pel as if the computation had been done in device coordinates. Such errors can be 
avoided if calculations are done in device coordinates, or if there are no scaling (or rotational, or 
shear) elements in the transforms. Alternatively, the problems can be reduced, though not 
eliminated, by defining very fine world coordinates. 
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Drawing Process Check Errors 

Some GPI functions involve processing buffers of graphics orders or retained graphics segments (the 
data for which consists of graphics orders). These functions can give rise to Drawing Process Check 
(DPC) errors if an order is found that either is not valid in its context or that contains invalid data. If 
this happens, processing of the function stops and the error is recorded. Note that orders up to the 
one found to be in error are processed by the function, and output occurs if drawing is being 
performed. 

Each function that can return these errors has Drawing Process Check errors in its error condition 
list. The full list of DPC errors is: 

PMERR_INV_IN_AREA 
PMERR_INV_IN_PATH 
PMERR_INV_IN_ELEMENT 
PMERR_ALREADY_IN_ELEMENT 
PMERR_STOP_DRAW_OCCURRED (warning) 

PMERR_PATH_INCOMPLETE 

PMERR_AREA_INCOMPLETE 

PMERRJMAGEJNCOMPLETE 

PMERR_INV_ORDER_LENGTH 

PMERR_NOT_IN_IMAGE 

PMERR_NOT_IN_AREA 

PMERR_NOT_IN_ELEMENT 

PMERR_NOT_IN_PATH 

PMERR_INSUFFICIENT_MEMORY 

PMERR_SEG_CALL_STACK_EMPTY 

PMERR_SEG_CALL_STACK_FULL 

PMERR_TRUNCATED_ORDER 

PMERR_CALLED_SEG_NOT_FOUND 

PMERR_DYNAMIC_SEG_SEQ_ERROR 

PMERR_PROLOG_ERROR 

PMERR_INV_IN_VECTOR_SYMBOL 


GPI Functions by Functional Area 

The following table shows how all of the Graphics Programming Interface (GPI) functions are related 
within functional areas. 


C Name 

C Name 

Curve Functions 

Attribute Setting Functions 

GpiQueryArcParams 

GpiSetArcParams 

GpiQueryDefArcParams 

GpiSetDefArcParams 

Primitive Functions 

GpiFullArc 

GpiPolyFillet 

GpiPartialArc 

GpiPolyFilletSharp 

GpiPointArc 

GpiPolySpline 

Area Functions 

Attribute Setting Functions 

GpiQueryPattern 

GpiSetPattern 

GpiQueryPatternRefPoint 

GpiSetPattern Ref Poi nt 

GpiQueryPatternSet 

GpiSetPatternSet 
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C Name 

C Name 

Primitive Functions 

GpiBeginArea 

GpiEndArea 

Bit-Map Support 

Creation and Selection Functions 

GpiCreateBitmap 

GpiQueryBitmapDimension 

GpiDeleteBitmap 

GpiSetBitmap 

GpiLoadBitmap 

GpiSetBitmapDimension 

Operations on Raw Bit Maps 

GpiQueryBitmapBits 

GpiQueryDeviceBitmapFormats 

GpiQueryBitmapinfoHeader 

GpiSetBitmapBits 

GpiQueryBitmapParameters 



Operations through Presentation Spaces 


GpiBitBIt GpiSetPel 

GpiDrawBits GpiWCBitBIt 

GpiQueryPel 


Resources and Defaults Functions 

GpiQueryBitmapHandle 

GpiSetBitmapId 

Character Functions 

Attribute Setting Functions 

GpiQueryCharAngle 

GpiSetCharAngle 

GpiQueryCharBox 

GpiSetCharBox 

GpiQueryCharBreakExtra 

GpiSetCharBreakExtra 

GpiQueryCharDirection 

GpiSetCharDirection 

GpiQueryCharExtra 

GpiSetCharExtra 

GpiQueryCharMode 

GpiSetCharMode 

GpiQueryCharSet 

GpiSetCharSet 

GpiQueryCharShear 

GpiSetCharShear 

GpiQueryTextAlignment 

GpiSetTextAlignment 

Primitive Functions 

GpiCharString 

GpiCharStringPosAt 

GpiCharStringAt 

GpiQueryCharStringPos 

GpiCharStringPos 

GpiQueryCharStringPosAt 


Resources and Defaults Functions 


GpiCreateLogFont GpiQueryKerningPairs 

GpiDeleteSetld GpiQueryLogicalFont 

GpiLoadFonts GpiQueryNumberSetlds 

GpiLoadPublicFonts GpiQuerySetlds 

GpiQueryCp GpiQueryTextBox 

GpiQueryDefCharBox GpiQueryWidthTable 

GpiQueryFaceString GpiSetCp 
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C Name C Name 

GpiQueryFontMetrics GpillnloadFonts 

GpiQueryFonts GpillnloadPublicFonts 

GpiQueryFullFontFileDescriptions GpiQueryFontAction 

Color and Mix Functions 



Attribute Setting Functions 


GpiQueryBackColor 


GpiSetBackColor 


GpiQueryBackMix 


GpiSetBackMix 


Resources and Default Functions 

GpiCreateLogColorTable GpiQueryNearestColor 

GpiQueryColorData GpiQueryRealColors 

GpiQueryColorlndex GpiQueryRGBColor 

GpiQueryLogColorTable 


Palette Manager Functions 

GpiAnimatePalette 

GpiQueryPalettelnfo 

GpiCreatePalette 

GpiSelectPalette 

GpiDeletePalette 

GpiSetPaletteEntries 


GpiQueryPalette 


Control Functions 

GpiAssociate 

GpiQueryPS 

GpiCreatePS 

GpiResetPS 

GpiDestroyPS 

GpiRestorePS 

GpiErrorSegmentData 

GpiSavePS 

GpiQueryDevice 

GpiSetPS 

Correlation and Boundary Determination Functions 

Bounds Data Functions 

GpiQueryBoundaryData 

GpiResetBoundaryData 

Correlation Data Functions 

GpiCorrelateChain 

GpiCorrelateSegment 


GpiCorrelateFrom 


Pick Aperture and Tag Functions 

GpiQueryDefTag 

GpiSetDefTag 

GpiQueryPickAperturePosition 

GpiSetPickAperturePosition 

GpiQueryPickApertureSize 

GpiSetPickApertureSize 

GpiQueryTag 

GpiSetTag 

Drawing Functions 

GpiDrawChain 

GpiQueryDrawControl 

GpiDrawDynamics 

GpiQueryDrawingMode 

GpiDrawFrom 

GpiQueryStopDraw 
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C Name 

C Name 

GpiDrawSegment 

GpiRemoveDynamics 

GpiErase 

GpiSetDrawControl 

GpiFloodFill 

GpiSetDrawingMode 

GpiGetData 

GpiSetStopDraw 

GpiPutData 

GpiPolygons 

General Attribute Functions 

Attribute Mode Functions 

GpiPop 

GpiSetAttrMode 

GpiQueryAttrMode 

GpiSetDefAttrs 

GpiQueryDefAttrs 



Attribute Strip Setting Functions 


GpiQueryAttrs 

GpiSetAttrs 

Image Functions 

Primitive Functions 

Gpilmage 


Line Functions 

Attribute Setting Functions 

GpiQueryLineEnd 

GpiSetLineEnd 

GpiQueryLineJoin 

GpiSetLineJoin 

GpiQueryLineType 

GpiSetLineType 

GpiQueryLineWidth 

GpiSetLine Width 

GpiQueryLineWidthGeom 

GpiSetLineWidthGeom 

Primitive Functions 

GpiBox 

GpiPolyLine 

GpiLine 

GpiQueryCurrentPosition 

GpiMove 

GpiSetCurrentPosition 


GpiPolyLineDisjoint 


Visibility Functions 

GpiPtVisible 

GpiRectVisible 

Marker Functions 

Attribute Setting Functions 

GpiQueryMarker 

GpiSetMarker 

GpiQueryMarkerBox 

GpiSetMarkerBox 

GpiQueryMarkerSet 

GpiSetMarkerSet 

Primitive Functions 

GpiMarker 

GpiPolyMarker 

Metafile Support 

GpiCopyMetaFile 

GpiQueryMetaFileBits 

GpiDeleteMetaFile 

GpiQueryMetaFileLength 

GpiLoadMetaFile 

GpiSaveMetaFile 
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C Name 


C Name 


GpiPlayMetaFile 

GpiComment 

GpiSetClipPath 

GpiBeginPath 

GpiCloseFigure 

GpiFillPath 

GpiOutlinePath 

GpiModifyPath 


GpiSetMetaFileBits 

Miscellaneous Functions 



Path Functions 

Path Clipping Functions 



Path Definition and Deletion Functions 
GpiEndPath 



Path Drawing Functions 

GpiStrokePath 



Path Manipulation Functions 



Region Support 

Clipping Region Functions 

GpiExcludeClipRectangle 

GpiQueryClipBox 

GpilntersectClipRectangle 

GpiQueryClipRegion 

GpiOffsetClipRegion 

GpiSetClipRegion 

Drawing Functions 

GpiFrameRegion 

GpiPaintRegion 

Region Functions 

GpiCombineRegion 

GpiPtlnRegion 

GpiCreateRegion 

GpiQueryRegionBox 

GpiDestroyRegion 

GpiQueryRegionRects 

GpiEqualRegion 

GpiRectlnRegion 

GpiOffsetRegion 

GpiSet Region 

GpiPathToRegion 



Segment Manipulation Functions 


Segment Content Manipulation Functions 


GpiBeginElement 

GpiQueryEditMode 

GpiDeleteElement 

GpiQueryElement 

GpiDeleteElementRange 

GpiQueryElementPointer 

GpiDeleteElementsBetweenLabels 

GpiQueryElementType 

GpiElement 

GpiSetEditMode 

GpiEndElement 

GpiSetElementPointer 

GpiLabel 

GpiSetElementPointerAtLabel 


GpiOffsetElementPointer 


Whole Segment Functions 


GpiCloseSegment 


GpiQuerySegmentNames 
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C Name 


C Name 


GpiDeleteSegment 

GpiDeleteSegments 

GpiOpenSegment 

GpiQuerylnitialSegmentAttrs 

GpiQuerySegmentAttrs 


GpiQueryDefViewingLimits 

GpiQueryGraphicsField 

GpiQueryViewingLimits 


GpiConvert 


GpiQueryPageViewport 


GpiRotate 

GpiScale 


GpiQuerySegmentPriority 

GpiSetlnitialSegmentAttrs 

GpiSetSegmentAttrs 

GpiSetSegmentPriority 


Transform Functions 

Clipping 

GpiSetDefViewing Limits 
GpiSetGraphicsField 
GpiSetViewingLimits 
Conversion Functions 

GpiConvertWithMatrix 
Device Transforms 

| GpiSetPageViewport 
Helper Functions 

GpiTranslate 


Modelling Transform Functions 


GpiCallSegmentMatrix 


GpiSetModelT ransformMatrix 


GpiQueryModelTransformMatrix 


GpiSetSegmentTransformMatrix 


GpiQuerySegmentTransformMatrix 


Viewing Transform Functions 


GpiQueryDefauitViewMatrix 


GpiSetDefauitViewMatrix 


GpiQueryViewingTransformMatrix 


GpiSetViewingTransformMatrix 
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GpiAnimatePalette 
Animate Palette 


#define INCL_GPILOGCOLORTABLE /* Or use INCL_GPI or INCL_PM */ 


LONG GpiAnimatePalette (HPAL hpal, ULONG uiFormat, ULONG uiStart, ULONG ulCount, 

PULONG aulTable) 


This function changes the color values of animating indexes in a palette. 


Parameters 

hpal (HPAL) - input 
Palette handle. 

uiFormat (ULONG) - input 

Format of entries in the table: 

LCOLF_CONSECRGB Array of RGB values, corresponding to color indexes uiStart upwards. 
Each entry is 4 bytes long. 

uiStart (ULONG) - input 
Starting index. 

This is relevant only for LCOLF_CONSECRGB. 

ulCount (ULONG) - input 

Count of elements in aulTable. 

This must be greater than or equal to 0. 

aulTable (PULONG) - input 

Start of the application data area. 

This contains the palette definition data. The format depends on the value of uiFormat. 

Each color value is a 4-byte integer, with a value of 
(F * 16777216) + (R * 65536) + (G * 256) + B 
where: 

F is a flag byte, which can take the following values (these can be ORed together if required): 
PC_RESERVED This index is an animating index. This means that the application might 

frequently change the RGB value, so the system should not map the logical 
index of the palette of another application to the entry in the physical 
palette used for this color. 

PC_EXPLICIT The low-order word of the logical color table entry designates a physical 

palette entry. This allows an application to show the contents of the device 
palette as realized for other logical palettes. This does not prevent the 
color in the entry from being changed for any reason. 

R is red intensity value 
G is green intensity value 
B is blue intensity value. 

The maximum intensity for each primary is 255. 
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GpiAnimatePalette - 
Animate Palette 


Returns 

Number of remapped colors. 

PAL_ERROR Error occurred 

Other Number of colors remapped (that Is, having entries In the physical color table). 

These are all animating indexes: they have the PC_RESERVED flag set on this 
function. If the palette is selected into more than one presentation space, the 
number returned is the maximum number of indexes that have entries in any of 
the relevant devices. 

Note that by the time an application receives this information, other applications 
using the palette may have caused the number to be changed. 


Possible returns from WinGetLastError 


PMERRJNVHPAL 

PMERR_INV_LENGTH_OR_COUNT 

PMERR_INV_COLOR_DATA 

PMERRINVCOLORFORMAT 

PMERR_INV_COLOR_START INDEX 

PMERRINSUFFICIENTMEMORY 

PMERR_PALETTE_BUSY 

PMERR_INV_IN_AREA 


An invalid color palette handle was specified. 

An invalid length or count parameter was specified. 

Invalid color table definition data was specified with 
GpiCreateLogColorTable. 

An invalid format parameter was specified with 
GpiCreateLogColorTable. 

An invalid starting index parameter was specified with a 
logical color table or color query function. 

The operation terminated through insufficient memory. 

An attempt has been made to reset the owner of a palette 
when it was busy. 

An attempt was made to issue a function invalid inside an 
area bracket. This can be detected while the actual 
drawing mode is draw or draw-and-retaln or during 
segment drawing or correlation functions. 


Remarks 

The animating indexes are those that have the PC_RESERVED flag set in the palette and also in the 
corresponding element of the aulTable array in this function. 

If an animating index already has an entry in the physical hardware palette (allocated from a 
previous call to WinRealizePalette), both that entry and the entry in the logical palette are changed. 

If there is not an entry in the physical palette, or the device does not support palette functions, the 
logical palette color is changed. This function does not allocate a new entry in the physical palette. 

This function ignores those elements in aulTable corresponding to non-animating indexes (those that 
do not have the PC_RESERVED flag set). Their colors are not changed. 

All presentation spaces that have this palette selected into them (see GpiSelectPalette) are updated 
with the effects of this function. It is not necessary to issue a WinRealizePalette function before the 
effects become visible. 

If a palette is selected into a presentation space that is associated with a device context of type 
OD METAFILE or OD_METAFILE_NOQUERY, only the final color values are recorded in the metafile. 

It is an error if a palette is selected into a presentation space that is within an area or path definition 
when this function is issued. 
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GpiAnimatePalette 
Animate Palette 


Related Functions 

• GpiCreatePalette 

• GpiDeletePalette 

• GpiQueryPalette 

• GpiQueryPalettelnfo 

• GpiSelectPalette 

• GpiSetPaletteEntries 

• WinRealizePalette 


Example Code 

This example uses GpiAnimatePalette to change the color values of the first four animating indexes 
in a palette. 


Idefine INCL_GPILOGCOLORTABLE /* Color Table functions */ 

linclude <os2.h> 


LONG IremapColors; /* number of remapped colors */ 

HPAL hpal; /* palette handle */ 


j ***************************************************************** 

* assume 4 entries in palette. * 

* The RGB values are calculated with the following formula: * 

* (F * 16777216) + (R * 65536) + (G * 256) + B * 

* where F = flag, PC_RESERVED or PC_EXPLICIT * 

* R = red intensity value * 

* G = green intensity value * 

* B = blue intensity value * 

* Thus, in the following table, red and green intensities are 0 * 

* while the blue intensity increases from 1 to 4. * 

***************************************************************** 


ULONG aulTable[4] = 

{ ( PC_RESERVED*16777216) + (0*65536) + (0*256) + 1, 
(PC_RESERVED*16777216) + (0*65536) + (0*256) + 2, 
(PC_RESERVED*16777216) + (0*65536) + (0*256) + 3, 
(PC_RESERVED*16777216) + (0*65536) + (0*256) + 4}; 


IremapColors = GpiAnimatePalette(hpal , LCOLF_CONSECRGB, 0L, 4L, 

aulTable) ; 
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GpiAssociate - 
Associate 


#define INCL_GPICONTROL /* Or use INCL_GPI or INCL_PM. Also in COMMON section */ 


BOOL GpiAssociate (HPS hps, HDC hdc) 


This function associates a graphics presentation space with, or dissociates it from, a device context. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

hdc (HDC) - input 

Device-context handle. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 

PMERRINVHPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_PSJS_ASSOCIATED An attempt was made to destroy a presentation or 

associate a presentation space that is still associated 
with a device context. 


PM E R R_DC_IS_ ASSOCIATED 


PMERR_INV_MICROPS_FUNCTION 

PMERRINVHDC 

PMERRREALIZENOTSUPPORTED 


An attempt was made to associate a presentation space 
with a device context that was already associated or to 
destroy a device context that was associated. 

An attempt was made to issue a function that is invalid in 
a micro presentation space. 

An invalid device-context handle or (micro presentation 
space) presentation-space handle was specified. 

An attempt was made to create a realizable logical color 
table on a device driver that does not support this 
function. 


PMERR_PATH_INCOMPLETE An attempt was made to open or close a segment either 

directly or during segment drawing, or to issue 
GpiAssociate while there is an open path bracket. 

PMERR_AREA_INCOMPLETE Either: 

• A segment has been opened, closed, or drawn. 

• GpiAssociate was issued while an area bracket was 
open. 

• A drawn segment has opened an area bracket and 
ended without closing it. 
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Remarks 

Any type of device context may be used. 

Subsequent drawing functions direct output to the associated device context. 

If a null handle is supplied for the device context, the presentation space is dissociated from its 
currently-associated device context. An associated presentation space cannot be associated with 
another device context, and an associated device context cannot be associated with another 
presentation space. 

An error occurs if you try to draw to a presentation space associated with a memory device context 
that has no bit map selected into it (see GpiSetBitmap). 

The processing described for GRES_ATTRS (see GpiResetPS) is performed on the presentation 
space. Also, bounds data is destroyed, the page viewport is reset to its default value (see 
GpiCreatePS), and any clip region and path definition are lost. The save/restore presentation-space 
stack (see GpiSavePS) is purged. 

Any palette selected into the presentation space remains selected. 

Any dynamic segments left drawn on the device are not subsequently removed by 
GpiRemoveDynamics. 


Related Functions 

• GpiCreatePS 

• GpiDestroyPS 

• GpiQueryDevice 

• GpiQueryPS 

• GpiResetPS 

• GpiRestorePS 

• GpiSavePS 

• GpiSetPS 

• GpiSetMarkerSet 

• GpiSetPatternSet 

Example Code 

This example releases the current device context and associates a new device context with the 
presentation space. 

#define INCL_GPICONTROL /* GPI control Functions */ 

#include <os2.h> 

HPS hps; /* presentation space handle */ 

HDC hdcPrinter; /* device context handle */ 

/* release the current device context */ 

GpiAssociate(hps, NULLHANDLE) ; 

/* associate a printer device context */ 

GpiAssociate(hps, hdcPrinter); 
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#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM. Also in COMMON section 7 


BOOL GpiBeginArea (HPS hps, ULONG flOptlons) 


This function begins the construction of an area. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

flOptlons (ULONG) - input 
Area options. 

This contains fields of option bits. For each field, one value should be selected (unless the 
default is suitable). These values can be ORed together to determine whether to draw boundary 
lines as well as the area interior: 

BA_NOBOUNDARY Do not draw boundary lines. 

BA_BOUNDARY Draw boundary lines (the default). 

Construction of the area interior: 

BA_ALTERNATE Construct interior in alternate mode (the default) 

BA_WINDING Construct interior in winding mode. 

Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRINVHPS 
PMERRPSBUSY 

PMERRINVAREACONTROL 

PMERR_INV_IN_PATH 

PMERRALREADYJNAREA 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid options parameter was specified with 
GpiBeginArea. 

An attempt was made to issue a function invalid inside a 
path bracket. 

An attempt was made to begin a new area while an 
existing area bracket was already open. 


Remarks 

The construction is terminated by the GpiEndArea function. 

You can use the following list of functions to define an area. They are used between the 
GpiBeginArea and GpiEndArea functions. 

• GpiBeginElement 

• GpiBox (with the IControl parameter set to DRO_OUTLINE) 

• GpiCallSegmentMatrix 

• GpiComment 

• GpiElement (containing a valid call) 
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• GpiEndElement 

• GpiFullArc (with the / Control parameter set to DRO_OUTLINE) 

• GpiLabel 

• GpiLine 

• GpiMove 

• GpiPartialArc 

• GpiPointArc 

• GpiPolyFillet 

• GpiPolyFilletSharp 

• GpiPolyLine 

• GpiPolySpline 

• GpiPop (that pops a valid call) 

• GpiSetArcParams 

• GpiSetAttrMode 

• GpiSetAttrs (setting valid line attributes only, or foreground color/mix (only) for other primitive 
types) 

• GpiSetColor 

• GpiSetCurrentPosition 

• GpiSetLineEnd 

• GpiSetLineJoin 

• GpiSetLineType 

• GpiSetLineWidth 

• GpiSetMix 

• GpiSetModelTransformMatrix 

GpiBox and GpiFullArc are valid only in an area bracket (that is, between the GpiBeginArea and 
GpiEndArea functions with the IControl parameter set to DRO_OUTLINE. Other values of this 
parameter on these functions cause an implicit area bracket around the function. 

Shading of the area is performed using the current pattern, as set by the GpiSetPattern function. The 
color and color-mixing modes that are current at the time GpiBeginArea is issued define the 
attributes to be applied to the pattern. The pattern reference point is also subjected to all of the 
transformations (including the model transformation) in force at the time of GpiBeginArea. 

The area boundary consists of one or more closed figures, each constructed by: 

• GpiBox 

• GpiFullArc 

• GpiPointArc 

• GpiLine 

• GpiPartialArc 

• GpiPolyFilletSharp 

• GpiPolyLine 

• GpiPolySpline 

• GpiPolyFillet 

The GpiSetColor and GpiSetMix functions can be used to control how the area boundary is to be 
colored. The GpiSetLineEnd, GpiSetLineJoin, GpiSetLineType, and GpiSetLineWidth functions can be 
used to control line attributes as required. GpiSetAttrs can be used as an alternative way of setting 
these attributes. GpiSetArcParams can be used to control the shape of arcs produced by GpiFullArc, 
GpiPointArc, and GpiPartialArc. 

The start of a new figure is indicated by: 

• GpiCallSegmentMatrix 

• GpiFullArc 

• GpiMove 

• GpiPop (or end of called segment), which pops current position or a model transform 

• GpiSetCurrentPosition 

• GpiSetModelTransformMatrix 

Note: GpiCloseFigure must not be issued within an area. 
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A GpiBox or GpiFuilArc function called within an area definition generates a complete closed figure. 
These functions must not be used within another figure definition. 

The starting point of each closed figure is the current position when this function is made, or the 
point specified by the function starting the figure. Figure construction continues until either a new 
figure is started, or GpiEndArea is called. 

Each figure should be closed, that is, the start and end points should be identical. If these points are 
not identical, they are joined by a straight line to arbitrarily close the figure. 

The area interior is constructed either in alternate mode or in winding mode. In alternate mode, 
whether any point is within the interior is determined by drawing an imaginary line from that point to 
infinity; if there is an odd number of boundary crossings, the point is inside the area, if there is an 
even number of crossings, it is not. 

In winding mode, the direction of the boundary lines is taken into account. Using the same imaginary 
line, the number of crossings is counted, as in alternate mode, but boundary lines going in one 
direction score plus one, and boundary lines going in the other direction score minus one. The point 
is in the interior if the final score is not zero. 

In either mode, all of the boundaries of the area are considered to be part of the interior. 

If the f /Options parameter of this function is BA_NOBOUNDARY, the boundary lines are nof drawn, 
but the shading ends at the boundaries. If the flOptions parameter specifies BA_BOUNDARY, the 
boundary lines and any lines added to close the figures are drawn. The lines are drawn using the 
current line attributes (which can be changed during construction) and shading occurs within the 
boundaries. 

The current position is not changed by this function, but it can be changed by the moves, arcs, fillets, 
and lines between this function and the GpiEndArea function, including any used to close figures. 

Area definitions cannot be nested. This function and the GpiEndArea function for one area must be 
within the same segment. 

You can have no more than 1 450 straight-line vertices that describe the area. 

During correlation in nonretained mode, a hit on any function within an area returns GPI_HITS in the 
GpiEndArea function. GPI_HITS is not returned on any of the primitives that occur within the area 
definition. 

Related Functions 

• GpiBeginPath 

• GpiEndArea 

• GpiSetPattern 

• GpiSetPatternRefPoint 

• GpiSetPatternSet 

• GpiPop 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiSetBackColor 

• GpiSetBackMix 

• GpiSetColor 

• GpiSetMix 
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Graphic Elements and Orders 

Element Type: OCODE_GBAR 
Order: Begin Area 

Example Code 

This example uses the GpiBeginArea function to draw an area. The area, an isosceles triangle, is 
drawn with boundary lines and filled using the alternate filling mode. 


Idefine INCL_GPIPRIMITIVES /* GPI primitive functions */ 
linclude <os2.h> 

HPS hps; /* presentation space handle */ 

POINTL ptl Start = { 0, 0 }; /* first vertex */ 

POINTL ptlTriangle[] = { 100, 100, 200, 0, 0, 0 }; /* vertices */ 

GpiMove(hps, SptlStart); /* move to starting point (0, 0) */ 

GpiBeginArea (hps, /* start the area bracket */ 

BA_B0UNDARY | /* draw boundary lines */ 

BA_ALTERNATE) ; /* fill interior with alternate mode */ 

GpiPolyLine(hps, 3L, ptlTriangle) ; /* draw the triangle */ 


GpiEndArea(hps) ; /* end the area bracket */ 
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#define I NCL_GPISEGEDITING /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiBeginElement (HPS hps, LONG IType, PSZ pszDesc) 


This function defines the start of an element within a segment. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

IType (LONG) - input 

Type to be associated with the element. 

Application-defined elements should have type values in the range X' 81 xxxxxx' through 
X'FFxxxxxx 1 to avoid conflict with system-generated elements. 

pszDesc (PSZ) - input 
Description. 

Variable-length character string, recorded with the type. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 


PMERRJNVHPS 

PMERR_PS_BUSY 

PMERRALREADYINELEMENT 

PMERRDESCSTRINGTRUNCATED 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An attempt was made to begin a new element while an 
existing element bracket was already open. 

An attempt was made to supply a description string with 
GpiBeginElement that was greater then the permitted 
maximum length (251 characters). The string was 
truncated. 


Remarks 

This function starts an element, stored in the current segment, in retain or draw-and-retain mode 
(see GpiSetDrawingMode). The element is drawn in draw or draw-and-retain mode. 

The drawing functions that form the contents of the element are passed on subsequent GPI functions 
(only those functions that can generate orders are logically part of the element). The element 
extends up to the next GpiEndElement function (or GpiCloseSegment, which causes an implicit 
GpiEndElementto be generated). 

Grouping drawing functions together into an element is useful if the set of functions is to be changed 
or replaced together at a later time. Drawing functions that are not explicitly grouped together in an 
element bracket (GpiBeginElement -GpiEndElement pair) generate a single element for each GPI 
function. 
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The GpiElement function, that itself generates a complete element, is not allowed within an element 
bracket. The GpiLabel function is also not allowed within an element bracket. Elements must not be 
nested within one segment. 


Related Functions 

• GpiCloseSegment 

• GpiDeleteElement 

• GpiDeleteElementRange 

• GpiDeleteElementsBetweenLabels 

• GpiElement 

• GpiEndElement 

• GpiLabel 

• GpiOffsetElementPointer 

• GpiQueryElement 

• GpiQueryElementPointer 

• GpiQueryElementType 

• GpiSetElementPointer 

• GpiSetElementPointerAtLabel 

Graphic Elements and Orders 

The element type is defined by the /Type parameter. 

Order: Begin Element 

Example Code 

This example uses the GpiBeginElement function to create an element in a segment. The element 
type is 1 and the element description is "Triangle". The application can use these later to identify the 
element. 

Idefine INCL_GPISEGEDITING /* GPI Segment Edit functions */ 
linclude <os2.h> 


HPS hps; 

POINTL ptl Start = { 0, 0 }; /* first vertex */ 

POINTL ptlTriangle[] = { 100, 100, 200, 0, 0, 0 }; /* vertices */ 

GpiBeginElement (hps, /* start element bracket */ 

1L, /* element type is 1 */ 

"Triangle"); /* element description */ 

GpiMove(hps, &ptlStart); /* move to start point (0, 0) */ 

GpiPolyLine(hps, 3L, ptlTriangle) ; /* draw triangle */ 

GpiEndElement (hps) ; /* end element bracket */ 
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^define INCL_GPIPATHS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiBeginPath (HPS hps, LONG IPath) 


This function specifies the start of a path. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

IPath (LONG) - input 
Path identifier. 

This must be 1. 

Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRINVHPS 

PMERR_PS_BUSY 

P M E RRJN V_P ATHJD 
PMERRALREADYINPATH 

PMERRINVINAREA 


Remarks 

Paths can be used for these purposes: 

• To generate lines and curves that have a geometric width (that is, a width that is subject to 
transformations): see GpiModifyPath and GpiStrokePath. 

• To generate lines and curves that have cosmetic width; see GpiOutlinePath. In particular, if the 
lines and curves are defined by characters drawn with an outline font, hollow characters are 
produced. Hollow characters can also be drawn outside paths, using the FATTR_SEL_OUTLINE 
FATTRS option with the GpiCreateLogFont function. 

• To generate nonrectangular shapes to be used for clipping; see GpiSetClipPath. 

• To generate shapes to be filled; see GpiFillPath. 

Note: Areas can also be used for filling; see GpiBeginArea. 

• To generate shapes to be converted to regions on which the region-combination function, 
GpiCombineRegion, can be used; see GpiPathToRegion. 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid path identifier parameter was specified. 

An attempt was made to begin a new path while an 
existing path bracket was already open. 

An attempt was made to issue a function invalid inside an 
area bracket. This can be detected while the actual 
drawing mode is draw or draw-and-retain or during 
segment drawing or correlation functions. 
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There are two stages in the process of describing a path: 

1. Path specification 

2. Path definition. 

Path Specification 

A path is specified by a number of figures, within a GpiBeginPath-GpiEndPath pair. Each figure is 
specified by line functions, or curve functions, or both, and is separated from other figures by one of 
these functions: 

• GpiCallSegmentMatrix 

• GpiCharString 

• GpiCharStringAt 

• GpiCharStringPos 

• GpiCharStringPosAt 

• GpiFullArc 

• GpiMarker 

• GpiMove 

• GpiPolyMarker 

• GpiPop (which restores the current position) 

• GpiSetCurrentPosition 

• GpiSetModelTransformMatrix 

A figure that is terminated by one of the functions in this list is said to be an open figure. A figure 
can also be terminated by a GpiCloseFigure function. This is said to be a closed figure. 

A GpiBox or GpiFullArc function within a path specifies a complete closed figure. These functions 
must not be used within another figure specification. 

GpiBeginPath initializes the path to be empty. 

Path specification functions are terminated by GpiEndPath. If there are no primitives between the 
GpiBeginPath and GpiEndPath functions, a null path is specified. The GpiEndPath that terminates 
this path specification must occur within the same segment as the GpiBeginPath function. 

Path specification functions can occur within a segment bracket. 

Path Definition 

The process of path definition causes a description of the path to be built in the currently associated 
device context. This description is used during any subsequent operation on the path. If the 
definition occurred by the drawing of a retained segment containing specification functions, these 
may subsequently be edited, with no effect on the path definition, until the segment is drawn again. 

If the drawing mode (see GpiSetDrawingMode) is set to draw or draw-and-retain, the path is defined 
as it is specified. If drawing mode is retain, path definition does not occur until the segment 
containing the path specification is drawn. 

When a path has been defined, the definition cannot be reopened. An attempt to redefine the path 
results in the definition being replaced. 

As the path definition is kept in the device context, association of the presentation space with a new 
device context means that the definition is lost. 

When it has been defined, a path can be used only in a single GpiFillPath, GpiStrokePath, 
GpiOutlinePath, GpiPathToRegion, or GpiSetClipPath function. Alternatively, a path can be modified 
once only with a GpiModifyPath function, and then used in a single GpiFillPath, GpiPathToRegion, or 
GpiSetClipPath function. If a path is required to be reused in a normal (not a micro) presentation 
space, it can be created in a retained segment (for example, using draw-and-retain mode [see 
GpiSetDrawingMode]). This segment must be drawn whenever the definition has to be recreated. 
This may be done even if the application is otherwise nonretained. Otherwise, the application must 
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reissue all the individual functions to reconstruct the path whenever the definition has to be 
recreated. 

A path definition is bound in device coordinates at the time the path is defined. If any transforms 
(other than the final windowing transform) are subsequently changed, they have no effect on the path 
itself. However, they affect the thickness if the path is to be stroked using GpiModifyPath, and they 
affect the pattern reference point if the path is to be filled with GpiFillPath. The transforms affect both 
the thickness and the pattern reference point if GpiStrokePath is used. 

Other Remarks 

Line type and line width have no effect on a path. Geometric line width takes effect if the path is 
stroked with GpiModifyPath or GpiStrokePath. 

These functions can be used inside the path bracket (that is, between the GpiBeginPath function and 
the following GpiEndPath function) to define the path: 


• GpiBeginElement (containing valid calls 
only) 

• GpiBox (must specify DRO_OUTLINE option) 

• GpiCallSegmentMatrix 

• GpiCharString 

• GpiCharStringAt 

• GpiCharStringPos 

• GpiCharStringPosAt 

• GpiCloseFigure 

• GpiComment 

• GpiElement (containing a valid call) 

• GpiEndElement 

• GpiFullArc (must specify DRO_OUTLINE 
option) 

• GpiLabel 

• GpiLine 

• GpiMarker 

• GpiMove 

• GpiPartialArc 

• GpiPointArc 

• GpiPolyFillet 

• GpiPolyFilletSharp 

• GpiPolyMarker 


GpiPolyLine 

GpiPolySpline 

GpiPop (if only a valid call is popped) 

GpiSetArcParams 

GpiSetAttrMode 

GpiSetAttrs 

GpiSetCharAngle 

GpiSetCharBox 

GpiSetCharDirection 

GpiSetCharMode 

GpiSetCharSet 

GpiSetCharShear 

GpiSetColor 

GpiSetCurrentPosition 

GpiSetLineEnd 

GpiSetLineJoin 

GpiSetLineType 

GpiSetLineWidth 

GpiSetMarker 

GpiSetMarkerBox 

GpiSetMarkerSet 

GpiSetMix 

GpiSetModelTransformMatrix 


The GpiCharString... functions, GpiQueryCharStringPos, GpiQueryCharStringPosAt, and 
GpiQueryTextBox are allowed only if the current font is an outline font. 

You can have no more than 1 450 straight line vertices that describe the path. Curves are 
decomposed into straight lines internally, and the number of resulting vertices are also subject to 
this limit. The same applies to outline font character strings. If solid-filled outline characters are to 
be drawn, it is better to do this outside a path definition. GpiModifyPath and GpiStrokePath increase 
the number of lines in the path, and will cause a path initially containing more than 297 straight lines 
to exceed the limit of 1 450. 

It is not valid for this function to occur within an area definition. 
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Related Functions 

• GpiBeginArea 

• GpiCloseFigure 

• GpiEndPath 

• GpiFillPath 

• GpiModifyPath 

• GpiOutlinePath 

• GpiPathToRegion 

• GpiSetClipPath 

• GpiStrokePath 

• GpiSetLineEnd 

• GpiSetLineJoin 

• GpiSetLineType 

• GpiSetLineWidth 

• GpiSetLineWidthGeom 

• GpiPop 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiSetBackColor 

• GpiSetBackMix 

• GpiSetColor 

• GpiSetMix 


Graphic Elements and Orders 

Element Type: OCODE_GBPTH 
Order: Begin Path 

Example Code 

This example uses the GpiBeginPath function to create a path. The path, an isosceles triangle, is 
given path identifier 1. After the path bracket is ended using GpiEndPath, a subsequent call to the 
GpiFillPath function draws and fills the path. 


Idefine INCL_GPIPATHS /* GPI Path functions */ 
linclude <os2.h> 

HPS hps; /* presentation space handle */ 
POINTL ptl Start = { 0, 0 }; /* first vertex */ 
POINTL ptlTrianglet] = { 100, 100, 200, 0, 0, 0 }; /* vertices */ 

GpiBeginPath(hps, 1L); /* start the path bracket */ 
Gpi Move (hps, &ptl Start) ; /* move to starting point */ 
GpiPolyLine(hps, 2L, ptlTriangle); /* draw two sides */ 
GpiCloseFigure(hps) ; /* close the triangle */ 
GpiEndPath(hps) ; /* end the path bracket */ 
Gpi Fill Path (hps, 1L, FPATH_ALTERNATE) ; /* draw and fill the path */ 


5-22 PM Programming Reference 



GpiBitBIt - 
Bit Bit 


#define INCL_GPIBITMAPS /* Or use INCL_GPI or INCL_PM. Also in COMMON section */ 


LONG GpiBitBIt (HPS hpsTarget, HPS hpsSource, LONG ICount, PPOINTL aptiPoInts, 
LONG IRop, ULONG fiOptlons) 


This function copies a rectangle of bit-map image data. 


Parameters 

hpsTarget (HPS) - input 

Target presentation-space handle. 

hpsSource (HPS) - Input 

Source presentation-space handle. 

ICount (LONG) - input 
Point count. 

Number of points specified in aptIPoints. 

If this is 3, a source rectangle of the same size as the target rectangle is used. If it is 4, 
stretching or compression is performed as necessary. If compression is performed, the 
flOptions parameter determines how eliminated rows or columns are handled. 

aptIPoints (PPOINTL) - input 
Point array. 

Array of ICount points, in the order Txl, Tyl, Tx2, Ty2, Sxl, Syl, Sx2, Sy2, where: 

Txl.Tyl Specify the lower-left corner of the target rectangle in target device coordinates. 

Tx2,Ty2 Specify the upper-right corner of the target rectangle in target device coordinates. 

Sxl, Syl Specify the lower-left corner of the source rectangle in source device coordinates. 

Sx2,Sy2 Specify the upper-right corner of the source rectangle in source device coordinates 
(not required if neither stretching nor compression is to be performed). 

IRop (LONG) - input 

Mixing function required. 

The value of /flop required to achieve any given result can be determined from the following 
table. The final value of each bit in every pel depends on the values of the corresponding bits in 
the pattern (P), source (S), and the original target value (T initial). Each row of the table shows 
one of the 8 possible combinations of these values. For each combination, mark the desired 
final target value in the last column. The 8 bits in this column then show the value of the least 
significant byte of /flop required to achieve this mixing function. For example, if the required 
mixing function is to copy the source to the target, then the T (final) column will be the same as 
the S column, and so /flop will have the binary value 11001100, or the hexadecimal value 00CC. 


P ST (initial) 


T (final) 


0 

0 

0 

0 

1 

1 

1 

1 


0 

0 

1 

1 

0 

0 

1 

1 


0 

1 

0 

1 

0 

1 

0 

1 


Bit 0 (least significant) 
Bit 1 
Bit 2 
Bit 3 
Bit 4 
Bit 5 
Bit 6 

Bit 7 (most significant) 


Mnemonic names are available for commonly used mixes: 
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ROP SRCCOPY 

/* SRC 

*/ 

ROP SRCPAINT 

/* SRC OR DST 

*/ 

ROP SRCAND 

/* SRC AND DST 

*/ 

ROP SRCINVERT 

/* SRC XOR DST 

*/ 

ROP SRCERASE 

/* SRC AND NOT(DST) 

*/ 

ROP NOTSRCCOPY 

/* NOT (SRC) 

*/ 

ROP NOTSRCERASE 

/* NOT(SRC) AND NOT(DST) 

*/ 

ROP MERGECOPY 

/* SRC AND PAT 

*/ 

ROP MERGEPAINT 

/* NOT(SRC) OR DST 

*/ 

ROP PATCOPY 

/* PAT 

*/ 

ROP PATPAINT 

/* NOT(SRC) OR PAT OR DST 

*/ 

ROP PATINVERT 

/* DST XOR PAT 

*/ 

ROP DSTINVERT 

/* NOT(DST) 

*/ 

ROP ZERO 

/* 0 

*/ 

ROP ONE 

/* 1 

*/ 


fiOptlons (ULONG) - input 
Options. 


The options define how eliminated lines or columns are treated if a compression is performed. 

Bits 15 through 31 of flOptions may be used for privately supported modes for particular devices. 

BBO_OR The default. If compression is necessary, logical-OR the eliminated rows or 

columns. This is useful for white on black. 

BBO_AND If compression is necessary, logical-AND the eliminated rows or columns. This 
is useful for black on white. 

BBOJGNORE If compression is necessary, ignore the eliminated rows or columns. This is 
useful for color. 


Returns 

Correlation and error indicators: 
GPI_OK Successful completion 

GPI_HITS Correlate hits 

GPI_ERROR Error occurred. 


Possible returns from WinGetLastError 


PMERRJNVHPS 

PMERRPSBUSY 

PMERR_INV_LENGTH_OR_COUNT 

PMERRJNVBITBLTMIX 

PMERR_INV_BITBLT_STYLE 

PMERRBITMAPNOTFOUND 

PMERRJNVCOORDINATE 

PMERRJNVRECT 

PMERRNOBITMAPSELECTED 

PM ERR_INCORRECT_DC_TYPE 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid length or count parameter was specified. 

An invalid /Hop parameter was specified with a GpiBitBIt 
or GpiWCBitBIt function. 

An invalid options parameter was specified with a 
GpiBitBIt or GpiWCBitBIt function. 

A attempt was made to perform a bit-map operation on a 
bit map that did not exist. 

An invalid coordinate value was specified. 

An invalid rectangle parameter was specified. 

An attempt has been made to operate on a memory 
device context that has no bit map selected. 

An attempt was made to perform a bit-map operation on a 
presentation space associated with a device context of a 
type that is unable to support bit-map operations. 
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PMERR_INCOMPATIBLE_BITMAP An attempt was made to select a bit map or perform a 

BitBIt operation on a device context that was 
incompatible with the format of the bit map. 


Remarks 

A rectangle of bit-map image data is copied from a bit map selected into a device context associated 
with the source presentation space, to a bit map selected into a device context associated with the 
target presentation space. Alternatively, either presentation space may be associated with a device 
context that specifies a suitable raster device, for example, the screen. 

Note: In either case, both source and target device contexts must apply to the same physical device. 
It is an error if this device does not support raster operations. 

Unless the device is a banded printer, both source and target may refer to the same presentation 
space. If so, the copy is nondestructive when source and target rectangles overlap. 

A rectangle can be specified in device coordinates, for both source and target. These rectangles are 
noninclusive; that is, they include the left and lower boundaries in device space, but not the right and 
upper boundaries. Thus, if the lower-left maps to the same device pel as the upper-right, that 
rectangle is considered to be empty. 

If the upper-right source point is specified, and the source and target rectangles are of different 
sizes, stretching, or compressing, or both, of the data occurs. flOptions specifies how eliminated 
rows or columns of bits are to be treated if compression occurs. Note that the pattern data is never 
stretched or compressed. 

The following current attributes of the target presentation space are used (other than for converting 
between monochrome and color, as described below): 

Area color 

Area background color 
Pattern set 
Pattern symbol. 

The color values are used in conversion between monochrome and color data. This is the only 
format conversion performed by this function. The conversions are: 

• Output of a monochrome pattern to a color device. 

In this instance, the pattern is converted first to a color pattern using the current area colors: 

- source Is -> area foreground color 

- source Os -> area background color. 

• Copying from a monochrome bit map to a color bit map (or device). 

The source bits are converted as follows: 

- source Is -* image foreground color 

- source Os -» image background color. 

• Copying from a color bit map to a monochrome bit map (or device). 

- source pels that are the source image background color -* image background color. 

- all other pels -» image foreground color. 

Note: In all of the above instances (except where the source image background color is used) it is 
the attributes of the target presentation space that are used. 

If the mix (/flop) does not call for a pattern, the pattern set and pattern symbol are not used. If it does 
not require a source (this is not valid when flOptions is in the range 1 through 3), hpsSource is not 
required and must be null. Sxl.Syl is also ignored in this instance. 
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Neither the source nor the pattern is required when a bit map, or part of a bit map, is to be cleared to 
a particular color. 

If the mix does require both source and pattern, a three-way operation is performed. 

If a pattern is required, dithering may be performed for solid patterns in a color that is not available 
on the device; see GpiSetPattern. 

If any of the source data is not available (when, for example, the source presentation space is 
connected to a screen window, and the source rectangle is not totally visible), the contents of the 
unavailable parts are undefined. This can be checked with GpiRectVisible before calling this 
function. 

This function is independent of drawing mode (see GpiSetDrawingMode); the effect always occurs 
immediately, and it is not retained even if the drawing mode is draw-and-retaln or retain. Its effect, 
however, is recorded in a metafile, but note that this is successful only if the metafile is replayed on 
a similar device, with draw drawing mode. 

The current position in both source and target presentation spaces is unchanged by this function. 

Note: This function must not be used when creating SAA-conforming metafiles; see “Metafile 
Restrictions” on page G-1. 

Related Functions 

• DevQueryCaps 

• DevOpenDC 

• GpiCreateBitmap 

• GpiDeleteBitmap 

• GpiDrawBits 

• GpiLoadBitmap 

• GpiQueryBitmapBits 

• GpiQueryBitmapDimension 

• GpiQueryBitmapHandle 

• GpiQueryBitmapParameters 

• GpiQueryDeviceBitmapFormats 

• GpiSetBitmap 

• GpiSetBitmapBits 

• GpiSetBitmapDimension 

• GpiSetBitmapid 

• GpiWCBitBIt 

• WinDrawBitmap 

• WinGetSysBitmap 
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Example Code 

This example uses GpiBitBIt to copy a bit map from one presentation space to another. Two 
presentation spaces are created: one associated with a memory context, and the other associated 
with a screen context. The function copies the memory context bit map that is 100 pels wide and 100 
pels high into a 50-by-50-pel rectangle at the location (300,400) on the screen, thereby causing the bit 
map to be visible in the window. Since the raster operation is ROP_SRCCOPY, GpiBitBIt replaces the 
image previously in the target rectangle. The function compresses the bit map to fit the new 
rectangle by discarding extra rows and columns as specified by the BBOJGNORE option. 


Idefine INCL_GPIBITMAPS /* Bit map functions */ 

Idefine INCL_DEV /* Device Function definitions */ 

Idefine INCL_GPIC0NTR0L /* GPI control Functions */ 

Idefine INCL_WINWIND0WMGR /* Window Manager Functions */ 

linclude <os2.h> 

HAB hab; /* anchor-block handle */ 

HPS hpsMemory; /* presentation-space handle */ 

HPS hpsScreen; /* presentation-space handle */ 

HDC hdcScreen; /* Device-context handle */ 

HDC hdcMemory; /* Device-context handle */ 

SIZEL sizl={0, 0}; /* use same page size as device */ 

/* context data structure */ 

DEV0PENSTRUC dop = {0L, "DISPLAY", NULL, OL, 0L, OL, 0L, OL, OL}; 
POINTL aptl [4] = { 

300, 400, /* lower-left corner of target */ 

350, 450, /* upper-right corner of target */ 

0, 0, /* lower-left corner of source */ 

100, 100 }; /* upper-right corner of source */ 

HWND hwnd; 


/* create memory device. context and presentation space, associating 
DC with the PS */ 

hdcMemory = DevOpenDC(hab, 0D_MEM0RY, , 5L, (PDEVOPENDATA)&dop, 
NULLHANDLE); 

hpsMemory = GpiCreatePS(hab, hdcMemory, Ssizl, GPIA_ASS0C 

| PU_PELS) ; 

/* create window device context and presentation space, associating 
DC with the PS */ 

hdcScreen = WinOpenWindowDC(hwnd) ; /* Open window device context */ 
hpsScreen = GpiCreatePS(hab, hdcScreen, &sizl, PU_PELS | GPIF_L0NG 

| GPIA_ASSOC) ; 


/* 

. get bit map, associate bit map with memory device context, 
draw into bit map 


*/ 

/* display the bit map on the screen by copying it from the memory 
device context into the screen device context */ 
GpiBitBlt(hpsScreen, hpsMemory, 4L, aptl, R0P_SRCC0PY, BB0_IGN0RE); 
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#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM. Also in COMMON section */ 


LONG GpiBox (HPS hps, LONG IControl, PPOINTL pptiPoint, LONG IHRound, LONG IVRound) 


This function draws a rectangular box with the current position and a specified position at diagonally 
opposite corners. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

IControl (LONG) - input 
Outline and fill control. 

Specifies if the interior of the box is to be filled, and if the outline is to be drawn: 

DRO_FILL Fill interior 

DRO_OUTLINE Draw outline 

DRO_OUTLINEFILL Draw outline and fill interior. 

pptiPoint (PPOINTL) - input 
Corner point. 

The coordinates of the corner that is diagonally opposite to the current position. 

IHRound (LONG) - input 
Corner-rounding control. 

Horizontal length of the full axis of the ellipse that is used for rounding at each corner. 

IVRound (LONG) - input 
Corner-rounding control. 

Vertical length of the full axis of the ellipse that is used for rounding at each corner. 

Returns 

Correlation and error indicators: 

GPI_OK Successful 

GPI_HITS Correlate hits 

GPI_ERROR Error. 

Possible returns from WinGetLastError 

PMERRJNVHPS 
PMERRPSBUSY 

PMERRINVBOXCONTROL 
PMERRINVCOORDINATE 
PMERRINVBOXROUNDINGPARM 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid control parameter was specified with GpiBox. 

An invalid coordinate value was specified. 

An invalid corner rounding control parameter was 
specified with GpiBox. 
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Remarks 

The sides of the box are parallel to the world coordinate x- and y-axes. 

The four corners of the box can be rounded with a quarter ellipse. The size of this ellipse is specified 
by IHRound and IV Round. If IHRound equals IVRound, the corners of the box are rounded with a 
quarter circle. 

If either IHRound or IVRound is zero, no rounding occurs. 

If the current position is (xO.yO) and pptIPoint is set to (xl.yl), the box is drawn from (xO.yO) to (xl.yO) 
to (xl.yl) to (xO.yl) to (xO,yO). The direction of drawing is significant in area winding mode; see 
GpiBeginArea. 

The current position is unchanged by this function. 

Either the outline of the box, or its interior, or both, can be drawn. 

If this function occurs within an area or path definition, it generates a complete closed figure 
(DRO_OUTLINE must be specified). It must not occur within any other figure definition. 

If correlation is in force, a hit always results if the pick aperture intersects the box boundary. 
However, if the pick aperture lies wholly within the box, a hit only occurs if the interior is being 
drawn (DRO_FILL or DROJDUTLINEFILL). 

Related Functions 

• GpiBox 

• GpiQueryCurrentPosition 

• GpiSetCurrentPosition 

• GpiSetLineJoin 

• GpiSetLineType 

• GpiSetLineWidth 

• GpiSetLineWidthGeom 

• GpiPop 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiSetBackColor 

• GpiSetBackMix 

• GpiSetColor 

• GpiSetMix 

Graphic Elements and Orders 

Element Type: OCODE_GCBOX 
Order: Box at Current Position 
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Example Code 

This example calls GpiBox to draw a series of rounded boxes, one inside another. 

Idefine INCL_GPIPRIMITIVES /* GPI primitive functions */ 

linclude <os2.h> 

HPS hps; /* presentation space handle */ 

POINTL ptl = { 100, 100 }; 

SHORT i; 

for (i = 0; i < 5; i++) 

GpiBox(hps, /* handle to a presentation space */ 

DR0_0UTLINE, /* draw the box outline */ 

&ptl , /* address of the corner */ 

i * 10L, /* horizontal corner radius */ 

i * 10L); /* vertical corner radius */ 
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#define INCL_GPITRANSFORMS /* Or use INCL_GPI or INCL_PM */ 


LONG GpiCallSegmentMatrix (HPS hps, LONG ISegment, LONG ICount, 

PMATRIXLF pmatlfArray, LONG lOptlons) 


This function calls a segment and applies an instance transform to it. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

ISegment (LONG) - input 

Identifier of segment to be called. 

This must be greater than 0. 

The segment must not be a chained segment. 

ICount (LONG) - input 
Number of elements. 

The number of elements of pmatlfArray to be examined, starting from the beginning of the 
structure. If ICount is less than 9, the remaining elements default to the corresponding elements 
of the identity matrix. If ICount = 0, the identity matrix is used. 

pmatlfArray (PMATRIXLF) - input 
Instance transform matrix. 

The third, sixth, and ninth elements, when specified, must be 0, 0, and 1, respectively. 

lOptlons (LONG) - input 
Transformation options. 

Specify how the transform defined by the pmatlfArray parameter should be used to modify the 
existing current model transform for the duration of the function. The existing transform is the 
concatenation, in the current function context, of the instance, segment, and model transforms, 
from the root segment downwards. 

TRANSFORM_REPLACE The previous model transform is discarded and replaced by the 

specified transform. 

TRANSFORM_ADD The specified transform is combined with the existing model 

transform. The existing transform precedes the new transform. This 
option is most useful for incremental updates to transforms. 

TRANSFORM_PREEMPT The specified transform is combined with the existing model 

transform. The new transform precedes the existing transform. 


Returns 

Correlation and error indicators: 

GPI_OK Successful 

GPI HITS Correlate hits 

GPI_ERROR Error. 

Possible returns from WinGetLastError 

PMERR INV HPS An invalid presentation-space handle was specified. 
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PMERR_PS_BUSY 

PMERRINVSEGNAME 

PMERR_INV_MICROPS_FUNCTION 

PMERR_INV_LENGTH_OR_COUNT 

PMERRINVMATRIXELEMENT 

PMERR_INV_TRANSFORM_TYPE 

P M ER R_C ALLEDSEGNOTFOU N D 
P M E R R_C ALLED SEG IS CH A I NE D 

PMERRCALLEDSEGISCURRENT 

PM E R R_SEG_C ALL_ST ACK_EMPTY 


An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid segment identifier was specified. 

An attempt was made to issue a function that is invalid in 
a micro presentation space. 

An invalid length or count parameter was specified. 

An invalid transformation matrix element was specified. 

An invalid options parameter was specified with a 
transform matrix function. 

An attempt was made to call a segment that did not exist. 

An attempt was made to call a segment that has a 
chained attribute set. 

An attempt was made to call a segment that is currently 
open. 

A call stack empty condition was detected when 
attempting a pop function during GpiPop or segment 
drawing. 


Remarks 

The instance transform specified is a model transform that is used to modify the current model 
transform, in a way that depends upon the value of the / Options parameter, before calling the 
segment. This new transform applies only to the called segment. On return, it is reset to the model 
transform in operation before the function was called. 

The transform is specified as a one-dimensional array of elements, being the first / Count elements of 
a 3-row by 3-column matrix ordered by rows. The order of the elements is: 

Matrix Array 


a b 0 
c d 0 
e f 1 


(a,b,0,c,d,0,e,f ,1) 


A point with coordinates (x,y) is transformed to the point 
(a*x + c*y + e, b*x + d*y + f) 

The called segment must have a unity transform for the viewing transform (see 
GpiSetViewingTransformMatrix). 

If scaling values greater than unity are given (which only applies if the presentation space coordinate 
format as set by the GpiCreatePS function is GPIF_LONG), it is possible for the combined effect of 
this and any other relevant transforms to exceed fixed-point implementation limits. This causes an 
error. 

Related Functions 

• GpiCloseSegment 

• GpiCorrelateSegment 

• GpiDeleteSegment 

• GpiDeleteSegments 

• GpiDrawSegment 

• GpiErrorSegmentData 
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• GpiOpenSegment 

• GpiQuerylnitialSegmentAttrs 

• GpiQuerySegmentAttrs 

• GpiQuerySegmentNames 

• GpiQuerySegmentPriority 

• GpiSetlnitialSegmentAttrs 

• GpiSetSegmentAttrs 

• GpiSetSegmentPriority 

• GpiSetSegmentTransformMatrix 

Graphic Elements and Orders 

Element Type: OCODE_GCALLS 
Order: Push and Set Model Transform 
Order: Call Segment 
Order: Pop 

Example Code 

This example calls the GpiCallSegmentMatrix function to draw a segment three times. Each time 
the segment is drawn, the instance transformation doubles in size. The result is three triangles with 
the last triangle twice the size of the second, and the second twice the size of the first. 


Idefine INCL_GPITRANSFORMS /* GPI Transform functions */ 

Idefine INCL_GPISEGMENTS /* Segment functions */ 

Idefine INCL_GPIPRIMITIVES /* GPI primitive functions */ 

linclude <os2.h> 

HPS hps; 

USHORT i; 

POINTL ptl Start = { 0, 0 }; /* first vertex */ 

POINTL ptlTrianglef] = { 100, 100, 200, 0, 0, 0 }; /* vertices */ 
MATRIXLF matlf Instance = { MAKEFIXED(1, 0), MAKEFIXED(0, 0), 0, 

MAKEFIXED(0, 0), MAKEFIXED(1, 0), 0, 

0, 0, l }; 

GpiOpenSegment (hps, 1L); /* opens segment */ 

GpiMove(hps, &ptl Start); /* moves to start point (0, 0) */ 

GpiPolyLine(hps, 3L, ptlTriangle) ; /* draws triangle */ 

GpiCloseSegment(hps) ; /* closes segment */ 


for (i = 0; i < 3; i++) 

{ 

/* 

* Draw the segment after adding the matrix to the model 

* transformation. 

*/ 

GpiCallSegmentMatrix (hps, 1L, 9, Smatlflnstance, TRANSFORMADD) ; 
matl f Instance. fxMll *= 2; 
matl f Instance. fxM22 *= 2 ; 

} 
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#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM. Also in COMMON section */ 


LONG GpiCharString (HPS hps, LONG ICount, PCH pchStrlng) 


This function draws a character string starting at the current position. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

ICount (LONG) - input 

Number of bytes in the string. 

The maximum number is 512. 

pchStrlng (PCH) - input 
Characters to be drawn. 


Returns 

Correlation and error indicators: 
GPI_OK Successful 

GPI_HITS Correlate hits 

GPI_ERROR Error. 


Possible returns from WinGetLastError 


PMERRINVHPS 

PMERR_PS_BUSY 

PMERR_INV_LENGTH_OR_COUNT 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid length or count parameter was specified. 


PMERR_FONT_AND_MODE_MISMATCH An attempt was made to draw characters with a character 

mode and character set that are incompatible. For 
example, the character specifies an image/raster font 
when the mode calls for a vector/outline font. 


Remarks 

Each character in the string is positioned so that its character reference point is at the current 
position. The current position is advanced after each character is drawn to give the position for the 
next character. 

The characters in the character string are selected from the current character set. The font from 
which the characters are selected depends on the current character mode. For a description of 
which fonts are used for each of the possible modes, see GpiSetCharMode. 

The degree to which approximation of the position and size of characters is allowed, and also the 
area used during correlation of the character string, is controlled by the character-mode attribute. 

After the string has been drawn, the current position is set to the end of the character string. This is 
the point at which the next character would have been drawn, had it existed. 
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Related Functions 

• GpiCharStringAt 

• GpiCharStringPos 

• GpiCharStringPosAt 

• GpiQueryCharStringPos 

• GpiQueryCharStringPosAt 

• GpiQueryDefCharBox 

• GpiSetCharAngle 

• GpiSetCharBox 

• GpiSetCharDirection 

• GpiSetCharMode 

• GpiSetCharSet 

• GpiSetCharShear 

• GpiPop 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiSetBackColor 

• GpiSetBackMix 

• GpiSetColor 

• GpiSetMix 

Graphic Elements and Orders 

Element Type: OCODE_GCCHSTM 

Order: Character String Move at Current Position 

Example Code 

This example uses the GpiCharString function to draw the string 'Hello'. The GpiMove function 
moves the current position to (100,100) so that the string starts there. 

*/ 


*/ 

*/ 


Idefine INCL_GPIPRIMITIVES /* GPI primitive functions 
linclude <os2.h> 

HPS hps; /* presentation space handle 

POINTL ptlStart; /* beginning of string 

ptlStart.x = 100L; 
ptl Start. y = 100L; 

/* Start string at (100, 100). */ 

GpiMove (hps, &ptl Start); 

/* Draw the 5-character string. */ 

GpiCharString (hps, 5L, "Hello"); 
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#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM. Also in COMMON section */ 


LONG GpiCharStringAt (HPS hps, PPOINTL pptiPoInt, LONG ICount, PCH pchStrlng) 


This function draws a character string starting at a specified position. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

pptiPoInt (PPOINTL) - input 
Starting position. 

Defines, in world coordinates, the position at which the first character in the string is to be 
placed. 

ICount (LONG) - input 

Number of bytes in the string. 

The maximum number is 512. 

pchStrlng (PCH) - input 
Characters to be drawn. 


Returns 

Correlation and error indicators: 
GPI_OK Successful 

GPI_HITS Correlate hits 

GPI_ERROR Error. 


Possible returns from WinGetLastError 


PMERRINVHPS 

PMERR_PS_BUSY 

PMERRJNVCOORDINATE 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid coordinate value was specified. 


PMERR_INV_LENGTH_OR_COUNT An invalid length or count parameter was specified. 

PMERR_FONT_AND_MODE_MISMATCH An attempt was made to draw characters with a character 

mode and character set that are incompatible. For 
example, the character specifies an image/raster font 
when the mode calls for a vector/outline font. 


Remarks 

The function GpiCharStringAt (hps, point, count, string) is equivalent to: 

GpiMove (hps, point) 

GpiCharString (hps, count, string) 

Each character in the string is positioned so that its character reference point is at the current 
position. The current position is advanced after each character is drawn to give the position for the 
next character. 
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The font from which the characters in the character string are selected depends on the current 
character mode. For a description of which fonts are used for each of the possible modes, see 
GpiSetCharMode. 

The degree to which approximation of the position and size is allowed, and also the area used during 
correlation of the character string, is controlled by the character-mode attribute. 

After the string has been drawn, the current position is set to the end of the character string. This is 
the point at which the next character would have been drawn, had it existed. 


Related Functions 

• GpiCharString 

• GpiCharStringPos 

• GpiCharStringPosAt 

• GpiQueryCharStringPos 

• GpiQueryCharStringPosAt 

• GpiQueryDefCharBox 

• GpiSetCharAngle 

• GpiSetCharBox 

• GpiSetCharDirection 

• GpiSetCharMode 

• GpiSetCharSet 

• GpiSetCharShear 

• GpiPop 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiSetBackColor 

• GpiSetBackMix 

• GpiSetColor 

• GpiSetMix 

Graphic Elements and Orders 

Element Type: OCODE_GCHSTM 

Order: Character String Move at Given Position 


Chapter 5. Graphics Functions 5-37 



GpiCharStringAt - 
Character String At 

Example Code 

This example uses the GpiCharStringAt function to draw the string "Hello" starting at the position 
(100,100). It then uses the GpiMove and GpiCharString functions to draw the same string at exactly 
the same position. 

Idefine INCL_GPIPRIMITIVES /* GPI primitive functions */ 
linclude <os2.h> 

HPS hps; /* presentation space handle */ 

POINTL ptl Start; 

ptlStart.x = 100L; 
ptlStart.y = 100L; 

/* Draw the string "Hello" at (100, 100). */ 

GpiCharStringAt (hps, &ptlStart, 5, "Hello"); 

/* These two calls are identical to the one above. */ 

GpiMove(hps, &ptlStart); 

GpiCharString(hps, 5L, "Hello"); 
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#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


LONG GpiCharStringPos (HPS hps, PRECTL prcIRect, ULONG flOptlons, LONG ICount, 
PCH pchString, PLONG alAdx) 


This function draws a character string starting at the current position, with formatting options. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

prcIRect (PRECTL) - input 
Rectangle structure. 

Defines, in world coordinates, the two corners of the rectangle that defines the background of the 
characters. It is ignored unless CHS_OPAQUE or CHS_CLIP is specified. 

flOptlons (ULONG) - input 
Formatting options. 

Option flags that can be used in combination: 

CHS_OPAQUE Background of characters is defined by the rectangle specified by 

prcIRect. The rectangle is to be shaded (with background color and 
overpaint) before drawing. 

CHS_VECTOR Increments vector (alAdx) is supplied. If zero, alAdx is ignored. 

CHS_LEAVEPOS Leave the current position at the start of the string. If not set, the current 

position is moved to the position at which the next character would have 
been drawn, had there been one. 

CHS_CLIP Clip the string to the rectangle. 

CHSUNDERSCORE Underscore the characters. See FATTR_SEL_UNDERSCORE on 
page A-37 in the FATTRS on page A-36 datatype. 

CHS_STRIKEOUT Overstrike the characters. See FATTR_SEL_STRIKEOUT in the FATTRS 
datatype. 

Other bits are reserved and must be zero. 

ICount (LONG) - input 

Number of bytes in the string. 

The maximum number is 512. 

pchString (PCH) - input 
Characters to be drawn. 

alAdx (PLONG) - input 
Increment values. 

Vector of increment values, in world coordinates. Any negative values are treated as if they 
were zero. 
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Returns 

Correlation and error indicators: 
GPI_OK Successful 

GPI_HITS Correlate hits 

GPI_ERROR Error. 


Possible returns from WinGetLastError 


PMERRINVHPS 

PMERR_PS_BUSY 

PMERR_INV_CHAR_POS_OPTIONS 

PMERR_INV_LENGTH_OR_COUNT 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid options parameter was specified with 
GpiCharStringPos or GpiCharStringPosAt. 

An invalid length or count parameter was specified. 


PMERR_INV_RECT An invalid rectangle parameter was specified. 

PMERR_FONT_AND_MODE_MISMATCH An attempt was made to draw characters with a character 

mode and character set that are incompatible. For 
example, the character specifies an image/raster font 
when the mode calls for a vector/outline font. 


Remarks 

A vector of increments can be specified, allowing control over the positioning of each character after 
the first. This vector consists of distances measured in world coordinates (along the baseline for 
left-to-right and right-to-left character directions, and along the shearline for top-to-bottom and 
bottom-to-top character directions). Increment i is the distance of the reference point of character 
i+1 from the reference point of character /'. The last increment may be needed to update the current 
position. 

These increments, when specified, set the widths of each character. 

A further option allows a rectangle to be specified that can be used as the background of the string 
instead of the normal background. This rectangle is painted using the current character background 
color and an overpaint mix (unless this is in a dynamic segment, when leave-alone is used). Both 
corners of the rectangle are specified, so that the rectangle is positioned independently of the 
current position. Points on the borders of the rectangle are considered to be included within the 
rectangle. 

Clipping of the string to the rectangle is also allowed. This is independent of whether the rectangle 
is actually drawn. 

The current position can be updated to the point at which the next character would have been drawn, 
had there been one, or it can be left at the start of the string. 


Related Functions 

• GpiCharString 

• GpiCharStringAt 

• GpiCharStringPosAt 

• GpiQueryCharStringPos 

• GpiQueryCharStringPosAt 

• GpiQueryDefCharBox 

• GpiSetCharAngle 

• GpiSetCharBox 

• GpiSetCharDirection 

• GpiSetCharMode 
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GpiCharStringPos - 
Character String Position 


• GpiSetCharSet 

• GpiSetCharShear 

• GpiPop 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiSetBackColor 

• GpiSetBackMix 

• GpiSetColor 

• GpiSetMix 

Graphic Elements and Orders 

Element Type: ETYPE_GCCHSTE 

Order: Character String Extended at Current Position 

Example Code 

This example uses GpiCharStringPos to display '13 Characters', starting at position 10,10 and 
clipped to a 100x100 rectangle in the lower left corner. 


Idefine INCL_GPIPRIMITIVES /* GPI Primitive functions */ 
linclude <os2.h> 

LONG lHits; /* correlation/error indicator */ 

HPS hps; /* Presentation-space handle */ 

POINTL pptl Start = {10L.1OL}; 

/* Starting position */ 

RECTL prclRect = {0L,0L,100L,100L}; 

/* Rectangle structure */ 

ULONG flOptions; /* Formatting options */ 

LONG 1 Count; /* Number of bytes in the string */ 

char pchString[25] ; /* Characters to be drawn */ 


GpiMove(hps, &pptlStart); 

flOptions = CHS_CLIP; /* clip text to rectangle */ 

1 Count = 13; 

strcpy(pchString,"13 characters") ; 

/* draw the string */ 

lHits = GpiCharStringPos (hps, &prclRect, flOptions, 1 Count, 

pchString, NULL); 
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GpiCharStringPosAt - 
Character String Position At 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


LONG GpiCharStringPosAt (HPS hps, PPOINTL pptlStart, PRECTL prcIRect, ULONG fiOptlons, 

LONG ICount, PCH pchStrlng, PLONG aiAdx) 


This function draws a character string starting at a specified position, with formatting options. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

pptlStart (PPOINTL) - input 
Starting position. 

prcIRect (PRECTL) - input 
Rectangle structure. 


Defines, in world coordinates, the two corners of the rectangle that defines the background of the 
characters. It is ignored unless CHS_OPAQUE or CHS_CLIP is selected. 

fiOptlons (ULONG) - input 
Formatting options. 


Option flags that can be used in combination: 


CHS_OPAQUE Background of characters is defined by the rectangle specified by 

prcIRect. The rectangle is to be shaded (with background color and 
overpaint) before drawing. 

CHS_VECTOR Increments vector {aiAdx) is supplied. If 0, aiAdx is ignored. 


CHS_LEAVEPOS If set, current position is unchanged by this function. If not set, current 
position is moved to the position at which the next character would have 
been drawn, had there been one. 


CHS_CLIP Clip the string to the rectangle. 

CHS_UNDERSCORE Underscore the characters. See FATTR_SEL_UNDERSCORE in the 
FATTRS datatype. 


CHSSTRIKEOUT Overstrike the characters. See FATTR_SEL_STRIKEOUT in the FATTRS 
datatype. 

Other bits are reserved and must be zero. 


ICount (LONG) - input 

Number of bytes in the string. 


The maximum number is 512. 


pchStrlng (PCH) - input 
Character string. 

aiAdx (PLONG) - input 
Increment values. 

Vector of increment values, in world coordinates. Any negative values are treated as if they 
were zero. 
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GpiCharStringPosAt - 
Character String Position At 


Returns 

Correlation and error indicators: 
GPI_OK Successful 

GPI_HITS Correlate hits 

GPI.ERROR Error. 


Possible returns from WinGetLastError 


PMERRINVHPS 

PMERRPSBUSY 

PMERRJNV_CHAR_POS_OPTIONS 

PMERRINVCOORDINATE 

PMERRJNVRECT 

PMERR_INV_LENGTH_OR_COUNT 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid options parameter was specified with 
GpiCharStringPos or GpiCharStringPosAt. 

An invalid coordinate value was specified. 

An invalid rectangle parameter was specified. 

An invalid length or count parameter was specified. 


PMERR_FONT_AND_MODE_MISMATCH An attempt was made to draw characters with a character 

mode and character set that are incompatible. For 
example, the character specifies an image/raster font 
when the mode calls for a vector/outline font. 


Remarks 

A vector of increments can be specified, allowing control over the position of each character after the 
first. This vector consists of distances measured in world coordinates (along the baseline for 
left-to-right and right-to-left character directions, and along the shearline for top-to-bottom and 
bottom-to-top character directions). Increment i is the distance of the reference point (for example, 
lower left corner) of character i+1 from the reference point of character /. The last increment may be 
needed to update the current position. 

These increments, if specified, set the widths of each character. 

A further option allows a rectangle to be specified that can be used as the background of the string 
instead of the normal background. This rectangle is painted using the current character background 
color and an overpaint mix (unless this is in a dynamic segment, when leave-alone is used). Both 
corners of the rectangle are specified, so that the rectangle is positioned independently of current 
position. Points on the borders of the rectangle are considered to be included within the rectangle. 

Clipping of the string to the rectangle is also allowed. This is independent of whether the rectangle 
is actually drawn. 

Current position can be updated to the point at which the next character would have been drawn, had 
there been one, or it can be left at the start of the string. 
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GpiCharStringPosAt - 
Character String Position At 


Related Functions 

• GpiCharString 

• GpiCharStringAt 

• GpiCharStringPos 

• GpiQueryCharStringPos 

• GpiQueryCharStringPosAt 

• GpiQueryDefCharBox 

• GpiSetCharAngle 

• GpiSetCharBox 

• GpiSetCharDirection 

• GpiSetCharMode 

• GpiSetCharSet 

• GpiSetCharShear 

• GpiPop 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiSetBackColor 

• GpiSetBackMix 

• GpiSetColor 

• GpiSetMix 

Graphic Elements and Orders 

Element Type: ETYPE_GCHSTE 

Order: Character String Extended at Given Position 

Example Code 

This example uses GpiCharStringPosAt to display '13 Characters', starting at position 10,10 and 
clipped to a 100x100 rectangle in the lower left corner. 


Idefine INCL_GPIPRIMITIVES /* GPI Primitive functions */ 
linclude <os2.h> 

LONG lHits; /* correlation/error indicator */ 

HPS hps; /* Presentation-space handle */ 

POINTL pptl Start = {10L.10L}; 

/* Starting position */ 

RECTL rclRect = {0L,0L,100L,10OL}; 

/* Rectangle structure */ 

ULONG flOptions; /* Formatting options */ 

LONG 1 Count; /* Number of bytes in the string */ 

char pchString[14] ; /* Characters to be drawn */ 


flOptions = CHS_CLIP; /* clip text to rectangle */ 

1 Count = 13; 

strcpy (pchStri ng , " 13 characters " ) ; 

lHits = GpiCharStringPosAt (hps, &pptl Start, SrclRect, flOptions, 

ICount, pchString, NULL); 
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GpiCloseFigure - 
Close Figure 


#define INCL_GPIPATHS /* Or use INCL_GPI or INCL_PM 7 


BOOL GpiCloseFigure (HPS hps) 


This function closes a figure within a path specification. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRJNVHPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

Remarks 

The current figure is closed by a line drawn to the start point of the figure. 

This function need not be used if the path is to be filled (see GpiFillPath), or used as a clip path (see 
GpiSetClipPath), as any figures in the path that have not been closed are automatically closed at that 
time. It should be used, however, for any closed figures within paths that are subsequently to be 
stroked by GpiModifyPath or GpiStrokePath. 

This function must not be used outside a path specification. In particular, it must not be used within 
an area. 

Related Functions 

Prerequisite Functions 

• GpiBeginPath 

Other Related Functions 

• GpiEndPath 

• GpiModifyPath 

• GpiStrokePath 

Graphic Elements and Orders 

Element Type: OCODE_GCFIG 
Order: Close Figure 
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GpiCloseFigure 
Close Figure 


Example Code 

This example uses the GpiCloseFigure function to close a triangle drawn in a path bracket. The 
triangle starts at (0,0), and as the current position just before the GpiCloseFigure is (200,0), the 
function closes the triangle by drawing a line from (200,0) to (0,0). 

Idefine INCL_GPIPATHS /* GPI Path functions */ 

finclude <os2.h> 

HPS hps; /* presentation space handle */ 

POINTL ptl Start = { 0, 0 }; 

P0INTL ptlPoints[] = { 100, 100, 200, 0 }; 

*/ 

*/ 

*/ 

*/ 

*/ 


GpiBeginPath(hps, 1L); 
GpiMove(hps, &ptlStart); 
GpiPolyLine(hps, 2L, ptlPoints); 
GpiCloseFigure(hps) ; 

Gpi EndPath(hps) ; 


/* start the path bracket 
/* move to starting point 
/* draw two sides 
/* close the triangle 
/* end the path bracket 
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GpiCloseSegment - 
Close Segment 


#define INCL_GPISEGMENTS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiCloseSegment (HPS hps) 


This function closes the current segment. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 


PMERRINVHPS 

PMERR_PS_BUSY 

PMERRINVMICROPSFUNCTION 

PM E R R_NOT _IN_SEG 

PMERR_PATH INCOMPLETE 

PMERR AREA INCOMPLETE 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An attempt was made to issue a function that is invalid in 
a micro presentation space. 

An attempt was made to end a segment using 
GpiCloseSegment while not in a segment bracket. 

An attempt was made to open or close a segment either 
directly or during segment drawing, or to issue 
GpiAssociate while there is an open path bracket. 

Either: 

• A segment has been opened, closed, or drawn. 

• GpiAssociate was issued while an area bracket was 
open. 

• A drawn segment has opened an area bracket and 
ended without closing it. 


Remarks 

Closing a segment does not delete the segment or affect the graphics primitives that are drawn. 

Any attributes that have been preserved (see the AM_PRESERVE option of GpiSetAttrMode) are 
popped (restored) when the GpiCloseSegment function is issued in draw or draw-and-retaln modes, 
and at the end of the segment when the segment is subsequently drawn in draw-and-retaln or retain 
modes (see GpiSetDrawingMode). 

If an area or path is open when a segment is closed, the area or path is terminated. When the 
drawing mode is draw or draw-and-retain, a warning is given, but the close processing continues. 
No warning is given for retain mode, if a retained segment with an open area or path is drawn, an 
error occurs. 

If an element bracket is open when a segment is closed, the element bracket is first closed 
automatically. 
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GpiCloseSegment - 
Close Segment 


If this function is followed by primitives or attributes, without first opening a segment, the following 
may or may not have been reset to their default values: 

• Current attribute values and arc parameters 

• Current tag 

• Current model transform 

• Current position 

• Current clip path and viewing limits. 

Any such quantity can be assumed to contain its default value only if it is known either that it has not 
been changed from the default, or that last time it was changed, it was set to its default value. An 
application should not be written to depend on the values of these quantities immediately after 
GpiCloseSegment. 

Subsequent primitives, not preceded by an GpiOpenSegment function, are not retained, irrespective 
of the current drawing mode. 

The current viewing transform, however, is guaranteed to be reset to unity for primitives outside 
segments. 

Related Functions 

Prerequisite Functions 

• GpiOpenSegment 

Other Related Functions 

• GpiCallSegmentMatrix 

• GpiCorrelateSegment 

• GpiDeleteSegment 

• GpiDeleteSegments 

• GpiDrawSegment 

• GpiErrorSegmentData 

• GpiQuerylnitialSegmentAttrs 

• GpiQuerySegmentAttrs 

• GpiQuerySegmentNames 

• GpiQuerySegmentPriority 

• GpiSetlnitialSegmentAttrs 

• GpiSetSegmentAttrs 

• GpiSetSegmentPriority 

Example Code 

This example uses the GpiCloseSegment function to close a segment. The GpiOpenSegment opens 
the segment; GpiMove and GpiPolyLine draw a triangle. 


Idefine INCL_GPISEGMENTS /* Segment functions */ 
finclude <os2.h> 

HPS hps; /* presentation space handle */ 
POINTL ptl Start = { 0, 0 }; /* first vertex */ 
POINTL ptlTriangleD = { 100, 100, 200, 0, 0, 0 }; /* vertices */ 

GpiOpenSegment (hps, 1L); /* open the segment */ 
GpiMove(hps, &ptlStart); /* move to start point (0,0) */ 
GpiPolyLine(hps, 3L, ptlTriangle) ; /* draw triangle */ 
GpiCloseSegment (hps) ; /* close the segment */ 
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GpiCombineRegion - 
Combine Region 

#define INCL_GPIREGIONS /* Or use INCL_GPI or INCL_PM */ 

LONG GpiCombineRegion (HPS bps, HRGN hrgnDest, HRGN hrgnSrcl, HRGN hrgnSrc2, 

LONG IMode) 

This function combines two regions. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

The regions must be owned by the device identified by the currently associated device context. 

hrgnDest (HRGN) - input 
Handle of destination. 

hrgnSrcl (HRGN) - input 

Handle of first source region. 

hrgnSrc2 (HRGN) - input 

Handle of second source region. 

IMode (LONG) - input 
Method of combination: 

CRGN_OR Union of hrgnSrcl and hrgnSrc2 
CRGN_COPY hrgnSrcl only (hrgnSrc2 ignored) 

CRGN_XOR Symmetric difference of hrgnSrcl and hrgnSrc2 
CRGN AND Intersection of hrgnSrcl and hrgnSrc2 
CRGN_DIFF hrgnSrcl and not (hrgnSrc2). 

Returns 

Complexity of resulting region and error indicators: 

RGN_NULL Null region 

RGN_RECT Rectangular region 

RGN_COMPLEX Complex region 
RGN_ERROR Error. 

Possible returns from WinGetLastError 

PMERR INV HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_HRGN An invalid region handle was specified. 

PMERR REGION IS CLIP REGION An attempt was made to perform a region operation on a 

region that is selected as a clip region. 

PMERR_INV_REGION_MIX_MODE An invalid mode parameter was specified with 

GpiCombineRegion. 

PMERR_HRGN_BUSY An internal region busy error was detected. The region 

was locked by one thread during an attempt to access it 
from another thread. 
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GpiCombineRegion 
Combine Region 


Remarks 

Source and destination regions must all be of the same device class. The destination region can be 
one of the source regions. 

An error is raised if any of the specified regions are currently selected as the clip region (by 
GpiSetClipRegion). 


Related Functions 

• GpiCreateRegion 

• GpiDestroyRegion 

• GpiEqualRegion 

• GpiOffsetRegion 

• GpiPaintRegion 

• GpiPtlnRegion 

• GpiQueryRegionBox 

• GpiQueryRegionRects 

• GpiRectlnRegion 

• GpiSetRegion 

Example Code 

This example uses the GpiCombineRegion function to create a complex region consisting of 
everything in two rectangles except where they overlap. 

Idefine INCL_GPIREGIONS /* Region functions */ 

linclude <os2.h> 

HPS hps; /* presentation space handle */ 

HRGN hrgnl, hrgn2, hrgn3; 

RECTL rcl Recti = { 0, 0, 100, 100 }; 

RECTL rclRect2 = { 50, 50, 200, 200 }; 

/* create first region */ 

hrgnl = GpiCreateRegion(hps, 1L, &rclRectl); 

/* create second region */ 

hrgn2 = GpiCreateRegion(hps, 1L, &rclRect2); 

/* create empty region */ 

hrgn3 = GpiCreateRegion(hps, 0L, NULL); 

/* Combine first and second regions, replacing the empty region. */ 
GpiCombineRegion(hps, hrgn3, hrgnl, hrgn2, CRGN_X0R); 
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GpiComment - 
Comment 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM 7 


BOOL GpiComment (HPS hps, LONG ILength, PBYTE pbData) 


This function adds a comment to the current segment. 


Parameters 

tips (HPS) - input 

Presentation-space handle. 

ILength (LONG) - input 
Data length. 

The length of pbData in bytes. ILength must not be greater than 255. 

pbData (PBYTE) - input 
Comment string. 

No conversion of any kind is performed on the data. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRJNV HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_LENGTH_OR_COUNT An invalid length or count parameter was specified. 

Remarks 

An application can use this function to store some data of its own in the segment if the drawing mode 
(see GpiSetDrawingMode) is set to retain or draw-and-retain. It has no effect on drawing. The data 
can subsequently be retrieved by the application using GpiQueryElement or GpiGetData. 

Graphic Elements and Orders 

Element Type: OCODE_GCOMT 
Order: Comment 
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GpiComment - 
Comment 

Example Code 

This example uses the GpiComment function to comment the contents of a segment. 


Idefine INCL_GPIPRIMITIVES /* GPI primitive functions */ 
Idefine INCL_GPISEGMENTS /* Segment functions */ 
linclude <os2.h> 

HPS hps; /* presentation space handle */ 
POINTL ptlStart = { 0, 0 }; /* first vertex */ 


POINTL ptlTriangle[] = { 100, 100, 200, 0, 0, 0 }; /* vertices */ 

Gpi0penSegment(hps, 0L); /* open the segment */ 

GpiComment (hps, 18L, "Start point (0, 0)"); 

GpiMove(hps, &ptl Start); 

GpiComment (hps, 13L, "Draw triangle"); 

GpiPolyLine(hps, 3L, ptlTriangle) ; 

GpiCloseSegment(hps) ; /* close the segment */ 
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GpiConvert - 
Convert 


#define I NCL_GPITRANSFORMS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiConvert (HPS hps, LONG ISrc, LONG ITarg, LONG ICount, PPOINTL aptiPoInts) 


This function converts an array of coordinate pairs from one coordinate space to another. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

ISrc (LONG) - input 

Source coordinate space. 

ITarg (LONG) - input 

Target coordinate space. 

ICount (LONG) - input 

Number of coordinate pairs in aptIPoints. 

aptiPoInts (PPOINTL) - input/output 
Array of coordinate pair structures. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 


PMERRINVHPS 

PMERRPSBUSY 

PMERRINVCOORDINATE 

PMERR_INV_LENGTH_OR_COUNT 

PMERRINVCOORDSPACE 

PMERRCOORDINATEOVERFLOW 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid coordinate value was specified. 

An invalid length or count parameter was specified. 

An invalid source or target coordinate space parameter 
was specified with GpiConvert. 

An internal coordinate overflow error occurred. This can 
occur if coordinates or matrix transformation elements (or 
both) are invalid or too large. 


Remarks 

This function replaces each coordinate pair in aptIPoints with the converted values. 

Valid values for the ISrc and ITarg parameters are: 

CVTC_WORLD World coordinates 
CVTCMODEL Model space 

CVTC_DEFAULTPAGE Page space before default viewing transform 
CVTC_PAGE Page space after default viewing transform 
CVTC_DEVICE Device space. 


Conversions involving either world coordinates or model space should not be performed if the 
drawing mode (see GpiSetDrawingMode) is retain. 
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GpiConvert 

Convert 


Related Functions 

• GpiCreatePS 

• GpiSetDefauItViewMatrix 

• GpiSetModelTransformMatrix 

• GpiSetPageViewport 

• GpiSetSegmentTransformMatrix 

• GpiSetViewingTransformMatrix 

Example Code 

This example uses the GpiConvert function to convert the coordinates of the mouse pointer to the 
corresponding coordinates in world space. The system passes mouse coordinates to a window 
procedure in the WM_MOUSEMOVE message. The coordinates are device coordinates. After the 
coordinates are converted, the GpiMove uses them to move to a new location in world space. 

Idefine INCL_GPITRANSFORMS /* GPI Transform functions */ 

Idefine INCL_GPI PRIMITIVES /* GPI primitive functions */ 

#include <os2.h> 

MPARAM mpl; 

HPS hps; 

POINTL ptl ; 

case WM_M0USEM0VE: 

ptl.x = (LONG) SHORTlFROMMP(mpl) ; 
ptl .y = (LONG) SH0RT2FR0MMP(mpl); 

GpiConvert (hps, CVTC_DEVICE, CVTC_WORLD, 1L, &ptl); 

GpiMove(hps, &ptl); 
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GpiConvertWithMatrix - 
Convert with Matrix 


#define INCL_GPITRANSFORMS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiConvertWithMatrix (HPS hps, LONG ICount, PPOINTL aptiPoInts, LONG ICount, 

PMATRIXLF pmatlf Array) 


This function converts an array of (x,y) coordinate pairs from one coordinate space to another, using 
the supplied transform matrix. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

ICount (LONG) - input 
Point count. 

Number of coordinate pairs in aptIPoints. 

aptiPoints (PPOINTL) - input/output 

Array of (x,y) coordinate pair structures. 

ICount (LONG) - input 
Number of elements. 

The number of elements of pmatlf Array to be examined, starting from the beginning of the 
structure. If ICount is less than 9, remaining elements default to the corresponding elements of 
the identity matrix. If ICount = 0, the identity matrix is used. 

pmatlf Array (PMATRIXLF) - input 
Instance transform matrix. 

The third, sixth, and ninth elements, when specified, must be 0, 0, and 1, respectively. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid coordinate value was specified. 

An invalid length or count parameter was specified. 

An internal coordinate overflow error occurred. This can 
occur if coordinates or matrix transformation elements (or 
both) are invalid or too large. 


PMERR_INV_HPS 

PMERRPSBUSY 

PMERRINVCOORDINATE 

PMERR_INV_LENGTH_OR_COUNT 

PMERRCOORDINATEOVERFLOW 
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GpiConvertWithMatrix 
Convert with Matrix 


Remarks 

The array contains xl, yl, x2, y2 The input coordinates are replaced by the converted 

coordinates. 

Only the supplied transform matrix is used, all other current transforms are ignored by this function. 

The transform is specified as a one-dimensional array of elements, being the first ICount elements of 
a 3-row by 3-column matrix ordered by rows. The order of the elements is: 

Matrix Array 


a b 0 
c d 0 
e f 1 


(a,b,0,c,d,0,e,f,l) 


A point with coordinates (x,y) is transformed to the point 
(a*x + c*y + e, b*x + d*y + f) 

Example Code 

This example uses GpiConvertWithMatrix to convert two coordinate pairs to another coordinate 
space defined by the supplied matrix, which has only the first transform element defined. 


Idefine INC L_GP I TRANS FORMS /* GPI Transform functions */ 
linclude <os2.h> 

BOOL f Success; /* success indicator */ 
HPS hps; /* Presentation-space handle */ 
LONG ICountp; /* Point count */ 
POINTL aptl Points [2] = {{0L,0L},{1L,1L}}; 

/* Array of (x,y) coordinate pair 

structures */ 
LONG ICount; /* Number of elements */ 
MATRIXLF pmatlf Array; /* Instance transform matrix */ 


ICount = 1; /* examine only first element of transform matrix */ 

pmatlf Array. fxMll = 2; /* set first element of transform matrix */ 

fSuccess = GpiConvertWithMatrix(hps, ICountp, aptlPoints, 

ICount, &pmatl f Array ) ; 
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GpiCopyMetaFile - 
Copy Metafile 


#define INCL_GPIMETAFILES /* Or use INCL_GPI or INCL_PM */ 


HMF GpiCopyMetaFile (HMF hmf) 


This function creates a new metafile and copies the contents of an existing loaded metafile into it. 

Parameters 

hmf (HMF) - input 

Source metafile handle. 


Returns 

New metafile handle and error indicators: 

^0 New metafile handle 

GPI_ERROR Error. 

Possible returns from WinGetLastError 

PMERR_INV_HMF An invalid metafile handle was specified. 

PMERR_METAFILE_IN_USE An attempt has been made to access a metafile that is in 

use by another thread. 

PMERR_TOO_MANY_METAFILES_IN_USE The maximum number of metafiles allowed for a given 

process was exceeded. 

Remarks 

The source metafile must already be loaded or generated. It is identified by a metafile handle. The 
new metafile is identified by a handle that is returned by this function, so it may be used, for 
example, by GpiPlayMetaFile. 

The new metafile is owned by the process from which this function is issued. It cannot be accessed 
directly from any other process. If it still exists when the process terminates, it is automatically 
deleted by the system. 


Related Functions 

• GpiDeleteMetaFile 

• GpiLoadMetaFile 

• GpiPlayMetaFile 

• GpiQueryMetaFileBits 

• GpiQueryMetaFileLength 

• GpiSaveMetaFile 

• GpiSetMetaFileBits 
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GpiCopyMetaFile 
Copy Metafile 


Example Code 

This example uses the GpiCopyMetaFile function to make a copy of the metafile loaded using the 
GpiLoadMetaFile function. 

Idefine INCL_GPIMETAFILES /* Metafile functions */ 

linclude <os2.h> 

HAB hab; /* anchor block handle */ 

HMF hmf, hmf 2; /* metafile handle */ 

/* loads metafile from disk */ 

hmf = GpiLoadMetaFile(hab, "sample. met") ; 


hmf2 = GpiCopyMetaFile (hmf); 


/* copy the metafile */ 
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Correlate Chain 


#define INCL_GPICORRELATION /* Or use INCL_GPI or INCL_PM */ 


LONG GpiCorrelateChain (HPS hps, LONG IType, PPOINTL pptIPIck, LONG IMaxHits, 

LONG IMaxDepth, PLONG alSegTag) 


This function performs a correlate operation on the retained segment chain. It returns data for each 
tagged primitive that intersects the current aperture, as set by GpiSetPickApertureSize. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

IType (LONG) - input 
Segment type. 

Type of segment on which correlation is to be performed: 

PICKSEL_VISIBLE Only visible and detectable segments with nonzero identifiers are 
correlated. 

PICKSEL_ALL All segments with nonzero identifiers are correlated, regardless of the 
detectability and visibility attributes of the segments. 

pptIPIck (PPOINTL) - input 
Pick position. 

The position of the center of the pick aperture, in presentation page units. 

IMaxHits (LONG) - input 
Maximum hits. 

Maximum number of hits that can be returned in the alSegTag parameter. 

IMaxDepth (LONG) - input 
Number of pairs. 

Number of segment and tag pairs to be returned by each hit. 

alSegTag (PLONG) - output 
Segment identifiers and tags. 

An array consisting of segment identifiers and primitive tags in alternate elements. For each hit, 
a set of IMaxDepth segment identifiers and tag pairs is returned. 


Returns 

Number of hits and error indicators: 

>0 Number of hits that occurred 

GPI_ALTERROR Error. 


Possible returns from WinGetLastError 

PMERRJNVHPS 

PMERR_PS_BUSY 

PMERRJNVCOORDINATE 

PMERRJNVMAXHITS 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid coordinate value was specified. 

An invalid maxhits parameter was specified with 
GpiCorrelateSegment, GpiCorrelateFrom, or 
GpiCorrelateChain. 
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PMERR_INV_CORRELATE_DEPTH 


PMERRJNVMICROPSFUNCTION 

PMERR_INV_CORRELATE_TYPE 


An invalid maxdepth parameter was specified with 
GpiCorrelateSegment, GpiCorrelateFrom, or 
GpiCorrelateChain. 

An attempt was made to issue a function that is invalid in 
a micro presentation space. 

An invalid type parameter was specified with 
GpiCorrelateSegment, GpiCorrelateFrom, or 
GpiCorrelateChain. 


Remarks 

The data returned for each “hit” (or correlation) consists of a set of segment and tag pairs, starting 
with the correlated one and followed by the one that called that segment. This is repeated until 
either the root segment is reached or IMaxDepth segment and tag pairs are returned. 

Only primitives with a nonzero tag in segments with a nonzero identifier are correlated using this 
function. Primitives in segments called (to any depth in the hierarchy) from an unnamed segment 
are not eligible for correlation. 

The depth value specifies the number of sets of segment and tag pairs to be returned for each hit. If 
the root segment is reached before IMaxDepth values, the remaining values are set to zero. If more 
than IMaxDepth values are available, only that number is returned. 

The number of hits that occurred is returned in INumHits. 

A “hit” is an instance of a segment identifier and tag pair for which the primitives lie completely or 
partially within the specified aperture. Two different primitives in the same segment might have the 
same tag, and would therefore produce the same hit. This is counted as a single hit; the hit is 
recorded only once in the alSegTag parameter returned. The INumHits parameter, therefore, returns 
this distinct number of hits. Hits are returned in the reverse order of their occurrence. 

alSegTag is set to the hits that are found, up to the maximum defined in the IMaxHits parameter. 
Corresponding pairs of elements form the “hit” pairs. The number returned by the function therefore 
contains the number of sets of IMaxDepth pairs set if the IMaxHits parameter is greater than the 
number of hits detected. The number of elements set in the alSegTag parameter is twice the number 
returned by the function (subject to a maximum of IMaxHits) multiplied by the IMaxDepth. 

If the INumHits value returned by the function is greater than that specified in IMaxHits, more hits 
occurred than could be returned. If all hits are important, specify an array that is large enough to 
contain the maximum number of sets of hits that are expected. 

The draw controls (see GpiSetDrawControl) are ignored by this function. 

It may be necessary to ensure that attributes, model transform, current position, and viewing limits 
are reset to their default values, before processing the chain. This can be done by either ensuring 
that the first segment to be correlated does not have the ATTR_FASTCHAIN attribute (see 
GpiSetlnitialSegmentAttrs), or by issuing GpiResetPS before the GpiCorrelateChain. The latter 
method also resets the clip path to no clipping. 

If this function is followed by primitives or attributes, without first opening a segment, the processing 
is as described for GpiCloseSegment. 
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Examples 


Start segment 1 
Tag 10 
Call 2 

End segment 1 
Start segment 2 

Tag 20 Pick Aperture 

Call 3 



For IMaxHits = 1 at IMaxDepth = 2: 

segment tag 

2 21 

1 10 


Returned INumHits = 2. 


For IMaxHits = 2 at IMaxDepth = 4: 


segment 

tag 


2 

21 

hitl.l 

1 

10 

hitl.2 

0 

0 

hitl.3 

0 

0 

hitl.4 

3 

30 

hit2.1 

2 

20 

hi t2 . 2 

1 

10 

hit2.3 

0 

0 

hi t2.4 


Returned INumHits = 2. 

Related Functions 

• GpiCorrelateFrom 

• GpiCorrelateSegment 

• GpiSetDrawControl 

• GpiSetPickAperturePosition 

• GpiSetPickApertureSize 
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Correlate Chain 

Example Code 

This example uses GpiCorrelateChain to correlate, using an aperture of default size and centered at 
(200,200), on visible and detectable segments and requests one intersection (or hit) and one 
segment/tag pair for that hit to be returned. The segments will have been previously defined and 
created using GpiSetlnitialSegmentAttrs and GpiOpenSegment/GpiCloseSegment. 

Idefine INCL_GPICORRELATION /* GPI Correlation functions */ 
linclude <os2.h> 

BOOL f Success; /* success indicator */ 

SIZEL psizlSize={0L,OL}; /* size of pick aperture */ 

LONG INumHits; /* number of hits or error */ 

HPS hps; /* Presentation-space handle */ 

POINTL pptlPick = {200L.200L}; 

/* Pick (center of aperture) position */ 

LONG IMaxHits; /* Maximum hits to be returned */ 

LONG IMaxDepth; /* Number of pairs to be returned */ 

LONG alSegTag; /* Segment identifiers and tags */ 

fSuccess = GpiSetPickAperturePosition(hps, &pptl Pick) ; 

/* set aperture size (use default) */ 

fSuccess = GpiSetPickApertureSize(hps, PICKAP_DEFAULT, &ps i zl Size) ; 

/* return only one hit */ 

IMaxHits = 1L; 

/* return only one segment/tag pair per hit */ 

IMaxDepth = 1L; 

/* correlate on visible, detectable segment chains */ 

INumHits = GpiCorrelateChain (hps, PIC KSE L_V I S I B LE , &pptlPick, IMaxHits, 

IMaxDepth, &alSegTag); 
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Correlate From 


#define INCL_GPICORRELATION /* Or use INCL_GPI or INCL_PM */ 


LONG GpiCorrelateFrom (HPS hps, LONG IFirstSegment, LONG ILastSegment, LONG IType, 
PPOINTL pptiPIck, LONG IMaxHits, LONG IMaxOepth, 

PLONG aiSegTag) 


This function performs a correlate operation on a section of the retained segment chain. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

IFirstSegment (LONG) - input 

Specifies the first segment to be correlated. 

It must be greater than 0. 

ILastSegment (LONG) - input 

Specifies the last segment to be correlated. 

It must be greater than 0. 

IType (LONG) - input 

Type of segments on which correlation is to be performed: 

PICKSEL_VISIBLE Only visible and detectable segments with nonzero identifiers are 
correlated. 

PICKSEL_ALL All segments with nonzero identifiers are correlated, regardless of the 
detectability and visibility attributes of the segments. 

pptiPIck (PPOINTL) - input 
Pick position. 

The position of the center of the pick aperture, in presentation page units. 

IMaxHits (LONG) - input 
Maximum hits. 

Maximum number of hits that can be returned in the aiSegTag parameter. 

IMaxDepth (LONG) - input 
Number of pairs. 

Number of segment and tag pairs to be returned by each hit. 

aiSegTag (PLONG) - output 
Segment identifiers and tags. 

An array consisting of segment identifiers and primitive tags in alternate elements. For each hit, 
a set of IMaxDepth segment identifiers and tag pairs is returned. 
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Correlate From 


Returns 

Number of hits and error indicators: 

>0 Number of hits that occurred 

GPI_ALTERROR Error. 

Possible returns from WinGetLastError 

PMERRINVHPS 
PMERR_PS_BUSY 

PMERR_INV_CORRELATE_TYPE 

PMERRJNVCOORDINATE 
PMERRINVMAXHITS 

PMERRINVCORRELATEDEPTH 


PMERRINVMICROPSFUNCTION 

PMERRSEGNOTFOUND 
PMERRSEGNOTCHAINED 

PMERRINVSEGNAME 

Remarks 

The correlation operation starts at the segment identified by IFirstSegment and includes chained and 
called segments up to, and including, the segment identified by ILastSegment. 

Data is returned for each tagged primitive that intersects the pick aperture. The data returned for 
each “hit” (or correlation) consists of a set of segment and tag pairs, starting with the correlated one 
and followed by the one that called the segment. This is repeated until the root segment is reached 
or IMaxDepth values are returned. 

Only primitives with a nonzero tag (see GpiSetTag) in segments with a nonzero identifier are 
correlated using this function. Primitives in segments called (to any depth in the hierarchy) from a 
segment 0 are not eligible for correlation. 

The depth value specifies the number of sets of segment and tag pairs to be returned for each hit. If 
the root segment is reached before IMaxDepth values, the remaining values are set to zero. If more 
than IMaxDepth values are available, only that number is returned. 

The number of hits that occurred is returned in INumHits. 

A “hit" is an instance of a segment identifier and tag pair for which the primitives lie completely or 
partially within the specified aperture. Two different primitives in the same segment might have the 
same tag, and would therefore produce the same hit. This is counted as a single hit; the hit is 
recorded only once in the alSegTag parameter returned. The INumHits parameter, therefore, returns 
this distinct number of hits. Hits are returned in reverse order of their occurrence. 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid type parameter was specified with 
GpiCorrelateSegment, GpiCorrelateFrom, or 
GpiCorrelateChain. 

An invalid coordinate value was specified. 

An invalid maxhits parameter was specified with 
GpiCorrelateSegment, GpiCorrelateFrom, or 
GpiCorrelateChain. 

An invalid maxdepth parameter was specified with 
GpiCorrelateSegment, GpiCorrelateFrom, or 
GpiCorrelateChain. 

An attempt was made to issue a function that is invalid in 
a micro presentation space. 

The specified segment identifier did not exist 

An attempt was made to issue GpiDrawFrom, 
GpiCorrelateFrom or GpiQuerySegmentPriority for a 
segment that was not chained. 

An invalid segment identifier was specified. 
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Correlate From 


alSegTag is set to the hits that are found, up to the maximum defined in the IMaxHits parameter. 
Corresponding pairs of elements form the hit pairs. The number returned by the call therefore 
contains the number of sets of IMaxDepth pairs set if the IMaxHits parameter is greater than the 
number of hits detected. The number of elements set in the alSegTag parameter is twice the number 
returned by the function (subject to a maximum of IMaxHits) multiplied by the IMaxDepth. 

If the INumHits value returned by the function is greater than that specified in IMaxHits, more hits 
occurred than could be returned. If all hits are important, specify an array that is large enough to 
contain the maximum number of sets of hits that are expected. 

The draw controls (see GpiSetDrawControl) are ignored by this call. 

It may be necessary to ensure that attributes, model transform, current position, and viewing limits 
are reset to their default values, before processing the segments. This can be done either ensuring 
that the first segment to be correlated does not have the ATTR_FASTCHAIN attribute (see 
GpiSetlnitialSegmentAttrs), or by issuing GpiResetPS before the GpiCorrelateFrom. The latter 
method also resets the clip path to no clipping. 

If this function is followed by primitives or attributes, without first opening a segment, the processing 
is as described for GpiCloseSegment. 

If IFirstSegment does not exist, or is not in the segment chain, an error is raised. If ILastSegment 
does not exist, or is not in the chain, or is chained before IFirstSegment, no error is raised and 
processing continues to the end of the chain. 


Related Functions 

• GpiCorrelateChain 

• GpiCorrelateSegment 

• GpiSetDrawControl 

• GpiSetPickAperturePosition 

• GpiSetPickApertureSize 
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Correlate From 


Example Code 

This example uses GpiCorrelateFrom to correlate, using an aperture of default size and centered at 
(200,200), on visible and detectable segments within the given chain of 2 segments. It requests one 
intersection (or hit) and one segment/tag pair for that hit to be returned. The segments will have 
been previously defined and created using GpiSetlnitialSegmentAttrs and 
GpiOpenSegment/GpiCloseSegment. 


Idefine INCL_GPICORRELATION /* GPI Correlation functions */ 
linclude <os2.h> 


BOOL 

fSuccess; /* 

success indicator 

*/ 

SIZEL 

psizlSize; /* 

size of pick aperture 

*/ 

LONG 

INumHits; /* 

number of hits or error 

*/ 

HPS 

hps; /* 

Presentation-space handle 

*/ 

LONG 

1 FirstSegment; /* 

Specifies the first segment to be 
correlated 

*/ 

LONG 

lLastSegment; /* 

Specifies the last segment to be 
correlated 

*/ 

POINTL 

pptlPick = {200L.200L}; 



/* 

Pick (center of aperture) position 

*/ 

LONG 

IMaxHits; /* 

Maximum hits to be returned 

*/ 

LONG 

IMaxDepth; /* 

Number of pairs to be returned 

*/ 

LONG 

alSegTag; /* 

Segment identifiers and tags 

*/ 


fSuccess = GpiSetPickAperturePosition(hps, &pptl Pick) ; 

/* set aperture size (use default) */ 

fSuccess = GpiSetPickApertureSize(hps, PICKAP_DEFAULT, &psizlSize); 

/* define chain of two segments (1 and 2) */ 

1 FirstSegment = 1; 
lLastSegment = 2; 

/* return only one hit */ 

IMaxHits = 1L; 

/* return only one segment/tag pair per hit */ 

IMaxDepth = 1L; 

/* correlate on visible, detectable segments */ 

INumHits = GpiCorrelateFrom(hps, 1 FirstSegment, lLastSegment, 

PICKSEL_VISIBLE, &pptlPick, IMaxHits, 
IMaxDepth, SalSegTag); 
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Correlate Segment 


^define INCL_GPICORRELATION /* Or use INCL_GPI or INCL_PM 7 


LONG GpiCorrelateSegment (HPS hps, LONG ISegment, LONG IType, PPOINTL pptiPick, 

LONG IMaxHIts, LONG IMaxDepth, PLONG aiSegTag) 


This function performs a correlate operation on a specified segment. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

ISegment (LONG) - input 

Identifier of the segment to be correlated. 

It must be greater than 0. 

IType (LONG) - input 

Type of segments on which correlation is to be performed: 

PICKSEL_VISIBLE Only visible and detectable segments with nonzero identifiers are 
correlated. 

PICKSEL_ALL All segments with nonzero identifiers are correlated, regardless of the 
detectability and visibility attributes of the segments. 

pptiPick (PPOINTL) - input 
Pick position. 

The position of the center of the pick aperture, in presentation page units. 

IMaxHIts (LONG) - input 
Maximum hits. 

The maximum number of hits that can be returned in the aiSegTag parameter. 

IMaxDepth (LONG) - input 
Number of pairs. 

Number of segment/tag pairs to be returned by each hit. 

aiSegTag (PLONG) - output 
Segment identifiers and tags. 

An array consisting of segment identifiers and primitive tags in alternate elements. For each hit, 
a set of IMaxDepth segment identifiers and tag pairs is returned. 


Returns 

Number of hits and error indicators: 

>0 Number of hits that occurred 

GPI_ALTERROR Error. 


Possible returns from WinGetLastError 


PMERR INV HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_CORRELATE_TYPE An invalid type parameter was specified with 

GpiCorrelateSegment, GpiCorrelateFrom, or 
GpiCorrelateChain. 
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PMERR_INV_COORDINATE 

PMERRJNVMAXHITS 

PMERRJNVCORRELATEDEPTH 

PMERRINVMICROPSFUNCTION 

PMERR_SEG_NOT_FOUND 


An invalid coordinate value was specified. 

An invalid maxhits parameter was specified with 
GpiCorrelateSegment, GpiCorrelateFrom, or 
GpiCorrelateChain. 

An invalid maxdepth parameter was specified with 
GpiCorrelateSegment, GpiCorrelateFrom, or 
GpiCorrelateChain. 

An attempt was made to issue a function that is invalid in 
a micro presentation space. 

The specified segment identifier did not exist 


PMERR_INV_SEG_NAME 


An invalid segment identifier was specified. 


Remarks 

Data is returned for each tagged primitive that intersects the pick aperture. The data returned for 
each “hit” (or correlation) consists of a set of segment and tag pairs, starting with the correlated one 
and followed by the one that called that segment. This is repeated until the specified segment (which 
was not called by another segment) is reached, or IMaxDepth values are returned. 

The specified segment identifier must be nonzero. Only primitives with a nonzero tag (see 
GpiSetTag) are correlated using this function. 

The depth value specifies the number of sets of segment and tag pairs to be returned for each hit. If 
the specified segment is reached before IMaxDepth values, the remaining values are set to zero. If 
more than IMaxDepth values are available, only that number is returned. 

The number of hits that occurred is returned in INumHits. 

A “hit” is an instance of a segment identifier and tag pair for which the primitives lie completely or 
partially within the specified aperture. Two different primitives in the same segment might have the 
same tag, and would therefore produce the same hit. This is counted as a single hit; the hit is 
recorded only once in the alSegTag parameter returned. The INumHits parameter, therefore, returns 
this distinct number of hits. Hits are returned in reverse order of their occurrence. 

alSegTag is set to the hits that are found, up to the maximum defined in the IMaxHits parameter. 
Corresponding pairs of elements form the hit pairs. The number returned by the function, therefore, 
contains the number of sets of IMaxDepth pairs set if the IMaxHits parameter is greater than the 
number of hits detected. The number of elements set in the alSegTag parameter is twice the number 
returned by the function (subject to a maximum of IMaxHits ) multiplied by the IMaxDepth. 

If the INumHits value returned by the function is greater than that specified in IMaxHits, more hits 
occurred than could be returned. If all hits are important, specify an array that is large enough to 
contain the maximum number of sets of hits that are expected. 

The draw controls (see GpiSetDrawControl) are ignored by this function. This function differs from 
the other GpiCorrelate... functions because the segment to be correlated need not be a chained 
segment. 

It may be necessary to ensure that attributes, model transform, current position, and viewing limits 
are reset to their default values before processing the segment. This can be done either by ensuring 
that the segment to be correlated does not have the ATTR_FASTCHAIN attribute (see 
GpiSetlnitialSegmentAttrs) or by issuing GpiResetPS before the GpiCorrelateSegment. The latter 
method also resets the clip path to no clipping. 

If this function is followed by primitives or attributes without first opening a segment, the processing 
is as described for GpiCloseSegment. 
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Correlate Segment 


Related Functions 

• GpiCorrelateChain 

• GpiCorrelateFrom 

• GpiCallSegmentMatrix 

• GpiCloseSegment 

• GpiDeleteSegment 

• GpiDeleteSegments 

• GpiDrawSegment 

• GpiErrorSegmentData 

• GpiOpenSegment 

• GpiQuerylnitialSegmentAttrs 

• GpiQuerySegmentAttrs 

• GpiQuerySegmentNames 

• GpiQuerySegmentPriority 

• GpiSetDrawControl 

• GpiSetlnitialSegmentAttrs 

• GpiSetPickAperturePosition 

• GpiSetPickApertureSize 

• GpiSetSegmentAttrs 

• GpiSetSegmentPriority 
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Correlate Segment 


Example Code 

This example uses GpiCorrelateSegment to correlate, using an aperture of default size and centered 
at (200,200), on a visible and detectable segment and requests one intersection (or hit) and one 
segment/tag pair for that hit to be returned. The segment will have been previously defined and 
created using GpiSetlnitialSegmentAttrs and GpiOpenSegment/GpiCloseSegment. 


Idefine INCL_GPICORRELATION /* GPI Correlation functions */ 
linclude <os2.h> 


BOOL 

fSuccess; 

/* success indicator 

*/ 

SIZEL 

psizlSize; 

/* size of pick aperture 

*/ 

LONG 

INumHits; 

/* number of hits or error 

*/ 

HPS 

hps; 

/* Presentation-space handle 

*/ 

LONG 

1 Segment ; 

/* segment to be correlated 

*/ 

LONG 

lLastSegment; /* Specifies the last segment to be 
correlated 

*/ 

POINTL 

pptlPick = 

{200L.200L}; 

/* Pick (center of aperture) position 

*/ 

LONG 

IMaxHits; 

/* Maximum hits to be returned 

*/ 

LONG 

IMaxDepth; 

/* Number of pairs to be returned 

*/ 

LONG 

alSegTag; 

/* Segment identifiers and tags 

*/ 


fSuccess = GpiSetPickAperturePosition(hps, &pptl Pick); 

/* set aperture size (use default) */ 

fSuccess = GpiSetPickApertureSize(hps, PICKAP_DEFAULT, SpsizlSize); 

/* define segment */ 

1 Segment = 1; 

/* return only one hit */ 

IMaxHits = 1L; 

/* return only one segment/tag pair per hit */ 

IMaxDepth = 1L; 

/* correlate on visible, detectable segments */ 

INumHits = GpiCorrelateSegment(hps, lSegment, PICKSEL_VISIBLE, 

&pptlPick, IMaxHits, IMaxDepth, 
SalSegTag) ; 
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Create Bit Map 


#define INCL_GPIBITMAPS /* Or use INCL_GPI or INCL_PM */ 


H BITMAP GpiCreateBitmap (HPS hps, PBITMAPINFOHEADER2 pbmp2New, ULONG flOptions, 

PBYTE pblnitData, PBITMAPINF02 pbmi2lnfoTable) 


This function creates a bit map and returns the bit-map handle. 


Parameters 

bps (HPS) - input 

Presentation-space handle. 

The associated device should, if possible, hold the bit map in its own memory. Where this is not 
possible, main memory is used and the bit map is held in a format compatible with the device. 

pbmp2New (PBITMAPINFOHEADER2) - input 
Bit-map information header. 

This structure defines the format of the bit map to be created. 

flOptions (ULONG) - input 
Options: 

CBMJNIT Initialize the bit map with pblnitData 

If the bit map is stored on a device, the flOptions parameter is passed to the device. 
Bits 16 through 31 can be used for special features known to be supported by the 
particular device driver. 

pblnitData (PBYTE) - input 
Buffer address. 

The address in application storage from which initialization data is to be copied, if CBMJNIT is 
set. 

pbml2lnfoTable (PBITMAPINF02) - input 
Bit-map information table. 

This defines the format of the data in pblnitData. It is ignored if CBM JNIT is not set. 


Returns 

Bit-map handle and error indicators: 
^0 New bit-map handle 

GPI_ERROR Error. 


Possible returns from WinGetLastError 


PMERRINVHPS 

PMERR_PS_BUSY 

PMERRINVINFOTABLE 

P M E R RIN V_US AGEP ARM 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid bit-map info table was specified with a bit-map 
operation. 

An invalid options parameter was specified with 
GpiCreateBitmap. 


Chapter 5. Graphics Functions 5-71 






GpiCreateBitmap 
Create Bit Map 


Remarks 

On some devices it is possible to create the bit map in device memory. Even when this is not 
possible, a bit map always belongs to a particular device. The device is specified through the device 
context associated with the specified presentation space. The device context can be any device 
context that describes the physical device (such as any window device context for the screen). 

There are a number of standard bit-map formats that should normally be adhered to. Other formats 
can be used if supported by the device. 

. A newly created bit map can be filled with data supplied by the application. This is useful where the 
bit map always contains, or always starts with, the same image, captured in the application. A 
bit-map information structure is also passed, which defines the format and color usage of the 
initialization data. It is assumed that enough data is passed to initialize the entire bit map. 

Some bit-map functions, including those that draw into the bit map, require the bit map to be selected 
into a memory device context, using GpiSetBitmap. This is true whether device or main memory is 
used to hold the bit map. 

The bit map is owned by the process from which this function is issued. It cannot be accessed 
directly from any other process. If it still exists when the process terminates, it is automatically 
deleted by the system. 

Some restrictions apply when using this function. Refer to Appendix G, “Format of Interchange 
Files” on page G-1 for additional details. 


Related Functions 

• GpiBitBIt 

• GpiDeleteBitmap 

• GpiDrawBits 

• GpiLoadBitmap 

• GpiQueryBitmapBits 

• GpiQueryBitmapDimension 

• GpiQueryBitmapHandle 

• GpiQueryBitmapParameters 

• GpiQueryDeviceBitmapFormats 

• GpiSetBitmap 

• GpiSetBitmapBits 

• GpiSetBitmapDimension 

• GpiSetBitmapid 

• GpiWCBitBIt 

• WinDrawBitmap 

• WinGetSysBitmap 
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Create Bit Map 


Example Code 

The following example loads a bit map resource from memory and uses the GpiCreateBitmap 
function to create the bit map. This is similar to using the GpiLoadBitmap function, except it gives 
the application the chance to modify the bit map image data before creating the bit map. 


Idefine INCL_GPIBITMAPS 
Idefine INCL_DOSRESOURCES 
linclude <os2.h> 


/* GPI bit map functions 
/* Dos Resource functions 


*/ 

*/ 


HPS hps; /* presentation space handle 

/* address of bit map image data in 
resource 

BITMAPINF0HEADER2 bmih; /* bit map info structure 
HBITMAP hbm; /* bit map handle 

memset (&bmih,0, si zeof (BITMAPINF0HEADER2) ) ; 
bmih.cbFix = si zeof (BITMAPINF0HEADER2) ; 

bmih.cx = cx; 

bmih.cy = cy; 

bmih.cPlanes = 1; 

bmih.cBitCount = cBitCount; 

(hbm = GpiCreateBitmap(hps, &bmih, OL, NULL, NULL); 


*/ 

*/ 

*/ 
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Create Logical Color Table 


#define INCL_GPILOGCOLORTABLE /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiCreateLogColorTable (HPS bps, ULONG flOptions, LONG IFormat, LONG IStart, 

LONG ICount, PLONG alTable) 


This function defines the entries of the logical color table. 


Parameters 

bps (HPS) - input 

Presentation-space handle. 

flOptions (ULONG) - input 
Options: 

LCOL_RESET The color table is reset to its default values before processing the 

remainder of the data in this function. 

This value is assumed if the color table is currently in RGB mode and is 
being changed to index mode; that is, LCOLFJNDRGB or 
LCOLF_CONSECRGB is specified. 

The IFormat parameter must be LCOLFJNDRGB or LCOLF_CONSECRGB. 

LCOL PURECOLOR When this option is set only colors for solid patterns (see GpiSetPattern) 
available in the physical palette will be used. Only pure colors are used 
and no dithering is done. 

Other flags are reserved and must be 0. 

IFormat (LONG) - input 

Format of entries in the table: 

LCOLFJNDRGB Array of index/RGB pairs. Each pair is 8 bytes long: 4 bytes (local 

format) for the index, and 4 bytes for the color value. 

This sets the color table into index mode (and forces LCOL_RESET) if it 
is in RGB mode. 

The maximum index that can be loaded is returned in the 
CAPS_COLORJNDEX parameter of the DevQueryCaps function. 

Each index specified must be greater than or equal to 0. 

LCOLF CONSECRGB Array of RGB values, corresponding to color indexes IStart upwards. 
Each entry is 4 bytes long. 

This sets the color table into index mode (and forces LCOL_RESET) if it 
is in RGB mode. 

The maximum index that can be loaded is returned in the 
CAPS_COLORJNDEX parameter of the DevQueryCaps function. 

LCOLF_RGB Color index = RGB. 

This sets the color table into RGB mode. 


IStart (LONG) - input 
Starting index. 

This is relevant only for LCOLF_CONSECRGB. 

The starting index must be greater than or equal to 0. 
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(Count (LONG) - input 

Count of elements in alTable. 

This must be greater than or equal to 0. If 0 is specified, LCOLFJNDRGB and 
LCOLF_CONSECRGB have the same effect. 

For LCOLFJNDRGB, alTable must contain an even number of elements. ICount must be an even 
number. 

alTable (PLONG) - input 

Start of the application data area. 

This contains the color table definition data. The format depends on the value of I Format . 

Each color value is a 4-byte integer, with a value of 

(R * 65536) + (G * 256) + B 

where: 

R is red intensity value 
G is green intensity value 
B is blue intensity value. 

The maximum intensity for each primary is 255. 

The high order byte must be 0. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 


PMERRJNVHPS 

PMERR_PS_BUSY 

PMERR INV COLOR OPTIONS 

PMERR_INV_LENGTH_OR_COUNT 
PM ERR IN VCOLORD AT A 

P M E R R_IN V_COLOR_FO RM AT 

PMERRJNV_COLOR_START_INDEX 

PMERRREALIZENOTSUPPORTED 

P M E R R_P ALETTE _S ELECTED 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid options parameter was specified with a logical 
color table or color query function. 

An invalid length or count parameter was specified. 

Invalid color table definition data was specified with 
GpiCreateLogColorTable. 

An invalid format parameter was specified with 
GpiCreateLogColorTable. 

An invalid starting index parameter was specified with a 
logical color table or color query function. 

An attempt was made to create a realizable logical color 
table on a device driver that does not support this 
function. 

Color palette operations cannot be performed on a 
presentation space while a palette is selected. 
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Remarks 

This function can cause the color table to be reset to the default values. These are: 


CLR_BACKGROUND Reset color, used by GpiErase. This is the natural background color for the 
device. For a display, it is the default window color 
(SYSCLR_WINDOWTEXT; see WinSetSysColors). For a printer, it is the 
paper color. 


CLR_BLUE 

CLRRED 

CLRPINK 

CLRGREEN 

CLRCYAN 

CLR_YELLOW 

CLRNEUTRAL 


CLRDARKGRAY 

CLRDARKBLUE 

CLRDARKRED 

CLRDARKPINK 

CLRDARKGREEN 

CLRDARKC Y AN 

CLRBROWN 

CLRPALEGRAY 


The background color for the display can be changed by setting new system 
colors from the Control Panel. The background color for a printer can be 
changed by selecting a new paper color (if allowed by the presentation 
driver). 

Blue. 

Red. 

Pink (magenta). 

Green. 

Cyan (turquoise). 

Yellow. 

A device-dependent color that provides a contrasting color to 
CLR BACKGROUND. For a display, it is the default window text color 
(SYSCLR_WINDOWTEXT; see WinSetSysColors). For a printer, it is a color 
that contrasts with the paper color. 

The neutral color for the display can be changed by setting new system 
colors from the Control Panel. The neutral color for a printer can be 
changed by selecting a new paper color (if allowed by the presentation 
driver). 

Dark gray. 

Dark blue. 

Dark red. 

Dark pink. 

Dark green. 

Dark cyan. 

Brown. 

Pale gray. 


GpiErase clears the output of a device to the color defined by CLR_BACKGROUND. 

By default, presentation spaces have a logical color table consisting of the 16 default values given 
above. In index mode, these entries are always considered as part of the color table, unless they are 
explicitly overwritten. Color indexes outside this range, which have not been loaded, are not 
considered as part of the color table; it is an error to use such colors if the color table is in index 
mode. 


The system performs a mapping from the colors in the logical color table to those in the standard 
physical color table for that device. This mapping is used for all drawing and bit maps. Mixing is not 
predictable. 

The standard physical color table always includes the standard 16 colors, where this is physically 
possible. On devices that support more than 16 colors, there may be additional colors available to 
which the requested colors may be mapped. However, it cannot be ensured that these additional 
colors are the same on different devices. Applications that depend upon precise colors beyond the 
first 16 should use a palette (see GpiCreatePalette) on devices for which this is supported. 
DevQueryCaps can be used to determine whether the function is supported by the device; see 
CAPS_PALETTE_MANAGER. 

For a monochrome device (whether it is a display, bit map, printer, or some other type), a reset color 
is defined as follows: 

1 . Start with the appropriate item below: 

• The paper color, for a printer with no loaded color table 
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• SYSCLRWINDOW, for a monochrome display with no loaded color table 

• Color 0, for any device if a color table has been loaded. 

2. If this color is white or a light color, the reset color is set to white; otherwise, the reset color is 
set to black. 

The reset color is used for: 

• The color that GpiErase clears the output to 

• CLR_BACKGROUND (color 0), unless an RGB color table is in use 

• CLR_DEFAULT for GpiSetBackColor 

• Any color that has exactly the same RGB value as the reset color. 

Any other color becomes black if the reset color is white, and the converse. 

Note: There are restrictions on the use of this function when creating SAA-conforming metafiles; 
see “Metafile Restrictions” on page G-1. 

Related Functions 

• DevQueryCaps 

• GpiCreatePalette 

• GpiQueryColorData 

• GpiQueryColorlndex 

• GpiQueryLogColorTable 

• GpiQueryNearestColor 

• GpiQueryRealColors 

• GpiQueryRGBColor 

• WinSetSysColors 

Example Code 

This example uses the GpiCreateLogColorTable function to create a logical color table, using data 
from the previous logical color table. 

Idefine INCL_GPILOGCOLORTABLE /* Color Table functions */ 

linclude <os2.h> 

HPS hps; /* presentation space handle */ 

LONG al Tabl e [16] ; /* assume 16 entries */ 

/* retrieve the current table */ 

GpiQueryLogColorTable (hps, 0L, 0L, 16L, al Tabl e) ; 

alTable[l] = 0x000080; /* change the second entry to light blue */ 


GpiCreateLogColorTable(hps, /* presentation space */ 

0L, /* no special options */ 

LCOLFCONSECRGB, /* consecutive RGB values */ 

0L, /* start with color index 0 */ 

16, /* 16 entries */ 

al Table); /* RGB color values */ 
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#define INCL_GPILCIDS /* Or use INCL_GPI or INCL_PM */ 


LONG GpiCreateLogFont (HPS hps, PSTR8 pName, LONG ILcid, PFATTRS pAttrs) 


This function provides a logical definition of a font. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

pName (PSTR8) - input 
Logical font name. 

An 8-character name that can be used to describe the logical font. Its principal use is in 
interchange files, where it can help to identify the required font. For example, it can reference a 
file name that contains the font for a remote system. 

ILcid (LONG) - input 
Local identifier. 

The local identifier that the application uses to refer to this font. It must be in the range 0 
through 254. If 0 is specified, the properties of the default font are changed. The original default 
fontcan be restored by calling GpiDeleteSetld, with an ILcid parameter of LCID_DEFAULT or 
/ _LCID_ALL. 

If the ILcid parameter specifies a local identifier that is already being used to refer to a logical 
font, but is not the current pattern-set or marker-set local identifier, then the new definition 
replaces the old one. If ILcid specifies a local identifier that is already being used to refer to a 
logical font, and is the current pattern-set or marker-set local identifier, an error occurs. An 
error also occurs if the local identifier is currently used to refer to a bit map. 

pAttrs (PFATTRS) - input 

Attributes required of the font. 


Returns 

Match indicators: 


FONT_MATCH 

FONT_DEFAULT 

GPIERROR 


Font requirements matched successfully 

Font requirements not matched; a default font is used 

Error occurred. 


Possible returns from WinGetLastError 


PMERRINVHPS 

PMERR_PS_BUSY 

PMERRINVSETID 

PMERR_INV_FONT_ATTRS 

PMERR_FONT_NOT_LOADED 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid setid parameter was specified. 

An invalid attrs parameter was specified with 
GpiCreateLogFont. 

An attempt was made to create a font that was not loaded. 


PMERR_SETIDJN_USE An attempt was made to specify a setid that was already 

in use as the currently selected character, marker or 
pattern set. 
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PMERR_KERNING_NOT_SUPPORTED Kerning was requested on GpiCreateLogFont call to a 

presentation space associated with a device context that 
does not support kerning. 


Remarks 

The system uses the available physical font that most closely matches the requirements. Physical 
fonts can be: 

• Loaded at initialization time 

• Built into particular devices or device drivers 

• Private ones for this process, loaded by GpiLoadFonts. 

An application can force selection of a particular physical font by quoting the / Match value in FATTRS 
to be returned for the desired font by GpiQueryFonts. However, this method is only valid for a 
particular device/device driver combination on a single machine. This method should be avoided as 
a method for selecting fonts. 

Whichever method is used, the choice of physical font, which is made when this function is issued, is 
never subsequently changed for a particular logical font. 

The local identifier (ILcid) that the application decides to use to reference this logical font for later 
drawing operations is also specified; see GpiSetCharSet. 

If the face name is provided, GpiCreateLogFont tries to select the font with that face name. If the face 
name is empty, GpiCreateLogFont selects a default font. 

When a match number is provided, GpiCreateLogFont tries to find a font with the same match 
number and face name. If there is a mismatch at this point, GpiCreateLogFont acts as though the 
match number is 0 and starts the search again. 

When the match number is 0 and the calling program requests a bit-map font 

(FATTR_FONTUSE_OUTLINE not set), GpiCreateLogFont searches for a bit-map font with the required 
average character width (AveCharWidth) and maximum baseline extent (MaxBaselineExt), consistent 
with the usage flags. If this search fails, GpiCreateLogFont searches for an outline font with the 
required face name. 

When the match number is zero and the calling program requests an outline font 
(FATTR_FONTUSE_OUTLINE is set), GpiCreateLogFont searches for an outline font with the required 
selection flags. If that search fails, a default outline font is selected. If the match number is set to a 
positive number, a Presentation Manager font is selected. If the match number is negative, a font 
belonging to a physical device is selected. 

It is advisable to set the values of all the elements in the pAttrs structure. This is particularly 
important where printing, plotting, or interchange are concerned, as the target machine may need to 
substitute an existing device font for the requested font. 

To anticipate possible substitution by a vector font, values should be set for character angle, 
character shear and character box (using GpiSetCharAngle, GpiSetCharShear, and GpiSetCharBox 
respectively) before drawing any character strings. The GpiQueryFontMetrics function can be used 
to get the values of the character box height and width for a font. These are held in the fields 
lEmHeight and lEmlnc in the FONTMETRICS structure. 

Outline font characters are normally drawn filled. However, hollow characters are produced if the 
FATTR SEL OUTLINE flag is set in the pAttrs parameter. For small characters, outlining in this way 
can give a similar visual appearance to filled characters, with improved performance. 

There are restrictions on the use of non-installed fonts with certain device types. See GpiLoadFonts 
for more details. 
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If this function occurs within a path definition when the drawing mode (see GpiSetDrawingMode) is 
retain or draw-and-retain, its effect is not stored with the definition. 

Note: There are restrictions on the use of this function when creating SAA-conforming metafiles; 
see “Metafile Restrictions” on page G-1. 


Related Functions 

• GpiDeleteSetld 

• GpiLoadFonts 

• GpiQueryFontMetrics 

• GpiQueryFonts 

• GpiQueryKerningPairs 

• GpiQueryNumberSetlds 

• GpiQuerySetlds 

• GpiQueryWidthTable 

• GpiSetCharSet 

• GpiSetCharMode 

• GpiSetMarkerSet 

• GpiSetPatternSet 

• GpillnloadFonts 

Example Code 

This example uses the GpiCreateLogFont function to create a logical font with the local identifier 1. 
The logical font has the face name “Courier” and requested width and height of 12 pels. Once the 
font is created, the example sets the font using the local identifier and displays a string in the font at 
the point (100,100). 


Idefine INCL_GPILCIDS /* Font functions */ 
Idefine INCL_GPIPRIMITIVES /* GPI primitive functions */ 
linclude <os2.h> 

HPS hps; /* presentation space handle */ 
POINTL ptl = { 100, 100 }; 

FATTRS fat; 

fat.usRecordLength = sizeof(FATTRS) ; /* sets size of structure */ 
fat.fsSelection = 0; /* uses default selection */ 
f at. 1 Match = 0L; /* does not force match */ 
fat.idRegistry = 0; /* uses default registry */ 
fat.usCodePage = 850; /* code-page 850 */ 
fat.lMaxBasel ineExt = 12L; /* requested font height is 12 pels */ 
fat.lAveCharWidth = 12L; /* requested font width is 12 pels */ 
fat.fsType = 0; /* uses default type */ 


fat.fsFontUse = FATTR_F0NTUSE_N0MIX;/* doesn't mix with graphics */ 
/* Copy Courier to szFacename field */ 
strcpy (fat . szFacename , "Couri er" ) ; 


GpiCreateLogFont (hps, /* presentation space */ 

NULL, /* does not use logical font name */ 

1L, /* local identifier */ 

&fat); /* structure with font attributes */ 


GpiSetCharSet (hps, 1L); /* sets font for presentation space */ 

GpiCharStringAt(hps, &ptl , 5L, "Hello"); /* displays a string */ 
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#define INCL_GPILOGCOLORTABLE /* Or use INCL_GPI or INCL_PM */ 


HPAL GpiCreatePalette (HAB hab, ULONG fiOptlons, LONG IFormat, LONG ICount, 
PLONG aiTable) 


This function creates and initializes a color palette. 


Parameters 

hab (HAB) - input 

Anchor-block handle. 

fiOptions (ULONG) - input 
Options: 

LCOL_PURECOLOR The application does not want color dithering to create 

colors not available in the physical palette for solid 
patterns (see GpiSetPattern). If this option is set, only 
pure colors are used and no dithering is done. 

LCOL_OVERRIDE_DEFAULT_COLORS Override option for applications that need the full 

hardware palette. The system does not guarantee a 
consistent look to the user interface when this option is 
used. The override is only in effect while the overriding 
palette is in the foreground 

To combine these two options, OR the values together. 
Other flags are reserved and must be B'O'. 

IFormat (LONG) - input 

Format of entries in the table: 

LCOLF_CONSECRGB Array of (RGB) values. Each entry is 4 bytes long. This is currently the 
only supported value for this parameter. 

ICount (LONG) - input 

Count of elements in aiTable. 

This must be greater than zero. 

aiTable (PLONG) - input 

Start of the application data area. 

This contains the palette definition data. 

Each color value is a 4-byte integer, with a value of 
(F * 16777216) + (R * 65536) + (G * 256) + B 
where: 

F is a flag byte, which can take the following values (these can be ORed together if required): 
PC_RESERVED This index is an animating index. This means that the application might 
frequently change the RGB value and so the system should not map the 
logical index of another application's palette to the entry in the physical 
palette used for this color. 

PC_EXPLICIT The low-order word of the logical color table entry designates a physical 
palette slot from which the color definition is to be taken. This allows an 
application to show the actual contents of the device palette as realized for 
other logical palettes. This does not prevent the color in the slot from being 
changed for any reason. 
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R is red intensity value 
G is green intensity value 
B is blue intensity value. 

Each intensity value must be in the range 0 through 255. 


Returns 

Palette handle: 

^0 Palette handle 

GPI_ERROR Error occurred. 


An invalid options parameter was specified with a logical 
color table or color query function. 

An invalid length or count parameter was specified. 

Invalid color table definition data was specified with 
GpiCreateLogColorTable. 

An invalid format parameter was specified with 
GpiCreateLogColorTable. 

An invalid starting index parameter was specified with a 
logical color table or color query function. 

The operation terminated through insufficient memory. 


Possible returns from WinGetLastError 

PMERRJNVCOLOROPTIONS 

PMERR_INV_LENGTH_OR_COUNT 

PMERRJNVCOLORDATA 

PMERR_INV_COLOR_FORMAT 

PMERRJNVCOLORSTARTJNDEX 

PMERRINSUFFICIENTMEMORY 


Remarks 

The new palette contains only the entries set in the alTable parameter. All color indices outside this 
range are not considered part of the palette; it is an error to use such colors when this palette is 
selected. 

When a palette is realized (see WinRealizePalette), the lowest indices are considered first. The 
palette should therefore be ordered so that the most important colors have the lowest indices. 
Animating indices, which on realization can have their own individual slots in the physical palette, 
should be used only when necessary. 

Palettes should be created with only those color indices that the application requires and not 
unnecessarily create a large palette. The maximum index for a palette is not limited to 
CAPS_COLOR_INDEX. 

The palette can be selected into a presentation space using GpiSelectPalette. 


Related Functions 

• DevQueryCaps 

• GpiAnimatePalette 

• GpiDeletePalette 

• GpiQueryPalette 

• GpiQueryPalettelnfo 

• GpiSelectPalette 

• GpiSetPaletteEntries 

• WinRealizePalette 

• GpiCreateLogColorTable 
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Example Code 

The uses GpiCreatePalette to create and initialize a palette of 4 pure (no dithering) colors. 


Idefine INCL_GPILOGCOLORTABLE /* Color Table functions */ 
finclude <os2.h> 

HAB hab; /* anchor block handle */ 
HPAL hpal ; /* palette handle */ 
LONG 1 Format; /* table entry format */ 


I ***************************************************************** 

* assume 4 entries in palette. * 

* The RGB values are calculated with the following formula: * 

* (F * 16777216) + (R * 65536) + (G * 256) + B * 

* where F = flag, PC_RESERVED or PC_EXPLICIT * 

* R = red intensity value * 

* G = green intensity value * 

* B = blue intensity value * 

* Thus, in the following table, red and green intensities are 0 * 

* while the blue intensity increases from 1 to 4. * 

***************************************************************** 

ULONG aulTable[4] = 

{ ( PC_RESERVED*16777216) + (0*65536) + (0*256) + 1, 
(PC_RESERVED*16777216) + (0*65536) + (0*256) + 2, 
(PC_RESERVED*16777216) + (0*65536) + (0*256) + 3, 
(PC_RESERVED*16777216) + (0*65536) + (0*256) + 4}; 


hpal = GpiCreatePalette(hab, 0L, LCOLFCONSECRGB, 4L, aulTable); 
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#define INCL_GPICONTROL /* Or use INCL_GPI or INCL_PM. Also in COMMON section */ 


HPS GpiCreatePS (HAB hab, HDC hdc, PSIZEL psizISize, ULONG flOptions) 


This function creates a presentation space. 


Parameters 

hab (HAB) - input 

Anchor-block handle. 

hdc (HDC) - input 

Device-context handle. 


The handle of a device context with which the presentation space is to be associated, if 
GPIA_ASSOC is specified. This is mandatory for a micro presentation space (type GPIT_MICRO). 

psizISize (PSIZEL) - input 
Presentation-page size. 


The size of the presentation page defines a rectangle in presentation page space, with the 
bottom-left corner at the origin. This rectangle is used for these purposes: 

• Together with the page viewport, it defines the device transform. Whenever the 
presentation space is associated with a device context, a default page viewport is 
constructed, based on the presentation page size. 

• It defines the “area of interest” of the picture. This is recorded in a metafile, if one is 
generated from this presentation space. Note, however, that depending upon the device 
transform, information drawn outside it may sometimes be visible; it is not a clipping 
boundary. 

• If PU_ARBITRARY is specified, the page viewport is constructed such that the origin of the 
page rectangle maps to the origin of the default device rectangle (maximized window size, 
paper size, and so on), and either the right or top edges map, keeping the picture within the 
default device rectangle, and preserving its aspect ratio. 

If 0 is specified as either the width or the height, GPIA_ASSOC must also be specified, and a 
presentation page of default dimension for the device (see above) is assumed. For 
PU_ARBITRARY the pel dimensions are used. 

flOptions (ULONG) - input 
Options. 

This contains fields of option bits. For each field, one value should be selected (unless the 
default is suitable). These values can then be ORed together to generate the parameter. 


PS_UNITS 

Presentation-page size units. 

In each instance, the origin is at the bottom left. 
One of these values must be specified: 
PU_ARBITRARY Application-convenient units 
PU_PELS Pel coordinates 

PUJLOMETRIC Units of 0.1 mm 

PU_HIMETRIC Units of 0.01 mm 

PU_LOENGLISH Units of 0.01 inch 

PU HIENGLISH Units of 0.001 inch 
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PU_TWIPS Units of 1/1440 inch. 

PS_FORMAT 

Coordinate format. 

Indicates options to be used when storing coordinate values internally in the segment store. 

For most calls, the format is not directly visible to an application. However, it is visible 
during editing (for example, GpiQueryElement). The format also has an effect on the 
amount of storage required for segment store. If a metafile is generated from this 
presentation space, the format also controls the format of the orders in the metafile. 

Note: If GPIF_SHORT is selected, it is the responsibility of the application to ensure that the 
values passed for graphics coordinates are in the range —32 768 through +32 767, 
when the drawing mode is retain or draw-and-retain (see GpiSetOrawingMode), or if 
a metafile is being created. If in doubt, default or specify GPIF_LONG. 

Do not specify GPIF_SHORT if a metafile of unknown format is to be played into this 
presentation space with GpiPlayMetaFile. 

One of these can be selected, for a GPIT_NORMAL presentation space (for a GPIT_MICRO 
presentation space, only GPIF_DEFAULT is allowed): 

GPIF_DEFAULT Default local format (same as GPIF_LONG) 

GPIF_SHORT 2-byte integers 

GPIF_LONG 4-byte integers. 

PS_TYPE 

Presentation space. 

GPIT_NORMAL Normal presentation space; this is the default 
GPIT_MICRO Micro presentation space. 

Note: GPIA_ ASSOC must also be set if GPIT_MICRO is set. 

PS_MODE 

Mode. Reserved, must be 0 (default). 

PS_ASSOCIATE 

Association indicator. 

Indicates whether the new presentation space is to be associated with the specified device 
context: 

GPIA_NOASSOC No association is required. This is the default. 

GPIA_ASSOC Association with hdc required. 

Note: GPIA_ ASSOC must be set if GPIT MICRO is set. 


Returns 

Presentation-space handle: 

#0 Presentation-space handle 

GPI_ERROR Error. 


Possible returns from WinGetLastError 

PMERR INV ORJNCOMPAT OPTIONS An invalid or incompatible (with micro presentation 

space) options parameter was specified with 
GpiCreatePS or GpiSetPS. 

PMERR DC iS ASSOCIATED An attempt was made to associate a presentation space 

with a device context that was already associated or to 
destroy a device context that was associated. 
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PMERR_INV_HDC An invalid device-context handle or (micro presentation 

space) presentation-space handle was specified. 

PMERRJNV_PS_SIZE An invalid size parameter was specified with 

GpiCreatePS or GpiSetPS. 

Remarks 

There are two types of presentation spaces: 

• Micro presentation space 

• Normal presentation space. 

Only a restricted subset of calls is allowed to a micro presentation space; the main difference is that 
graphic segments (primitives, attributes, and so on) can be retained by the system, for subsequent 
redraw or editing, in a normal presentation space, but not in a micro presentation space. However, 
the storage and execution overheads are lower for a micro presentation space. 

An initial association of the new presentation space with a device context may be performed (this is 
mandatory for a micro presentation space), by specifying GPIA_ASSOC. 

When a presentation space is associated with a device context, either using this function with 
GPIA_ ASSOC, or explicitly with GpiAssociate, a page viewport in device space is automatically 
constructed, to which the page is mapped to form the device transform. The value of PSJJNITS and 
the psizISize parameter, are taken into account. 

In general, the size parameter can be safely set to zeroes except when using PU_ARBITRARY units. 
In that case, use a size in device coordinates obtained from DevQueryCaps. For units other than 
PU_PELS, a non-zero size can cause a transform to be in effect for the resulting PS. 

Related Functions 

• GpiAssociate 

• GpiDestroyPS 

• GpiQueryDevice 

• GpiQueryPS 

• GpiResetPS 

• GpiRestorePS 

• GpiSavePS 

• GpiSetPageViewport 

• GpiSetPS 

• WinGetPS 

• WinGetScreenPS 
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Example Code 

This example uses the GpiCreatePS function to create a micro presentation space for a memory 
device context. The function associates the presentation space with the device context and sets the 
page units to pels. By default, the presentation space is a normal presentation space that uses local 
storage format. 


Idefine INCL_GPICONTROL /* GPI control Functions */ 

linclude <os2.h> 


HAB hab; 
HDC hdc; 
HPS hps; 
SIZEL sizl 


{ 0 , 0 }; 


/* anchor block handle 
/* device context handle 
/* presentation space handle 
/* use same page size as device 


^************************** 
* context data structure * 


*/ 

*/ 

*/ 

*/ 


************************** j 

DEVOPENSTRUC dop = {0L, "DISPLAY", NULL, 0L, 0L, 


0L, 0L, 0L, 0L}; 


/* create memory device context */ 

hdc = DevOpenDC(hab, 0D_MEM0RY , "*", 5L, ( PDEVOPENDATA )&dop , NULLHANDLE); 

/* Create the presentation and associate the memory device 
context. */ 

hps = GpiCreatePS(hab, hdc, &sizl, PU_PELS | 

GPIT_MICRO | GPI A_ASS0C) ; 
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GpiCreateRegion 
Create Region 


#define INCL_GPIREGIONS /* Or use INCL_GPI or INCL_PM */ 


HRGN GpiCreateRegion (HPS hps, LONG ICount, PRECTL arcIRectangles) 


This function creates a region, for a particular class of device, using a series of rectangles. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

A region suitable for use with the currently associated device is created. 

ICount (LONG) - input 

The number of rectangles. 

The number specified in arcIRectangles. If ICount is 0, an empty region is created, and 
arcIRectangles is ignored. 

arcIRectangles (PRECTL) - input 
An array of rectangles. 

The rectangles are specified in device coordinates. 

For each rectangle in the array, the value of xright must be greater than (or equal to) xleft, and 
ytop must be greater than (or equal to) y bottom. 


Returns 

Region handle: 

^0 Region handle 

RGN_ERROR Error. 

Possible returns from WinGetLastError 

PMERRJNVHPS 
PMERRPSBUSY 

PMERR_INV_LENGTH_OR_COUNT 
PMERRJNVCOORDINATE 
PMERRJNVRECT 

Remarks 

The new region is defined by the logical-OR of all of the rectangles specified. Points on the 
right-hand and top boundaries are not included in the region. Points on the left-hand and bottom 
boundaries, that are not also on the right-hand or top boundaries (that is, the top-left and bottom-right 
corner points), are included. 

The region is owned by the process from which this function is issued. It cannot be accessed directly 
from any other process. If it still exists when the process terminates, it is automatically deleted by 
the system. 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid length or count parameter was specified. 

An invalid coordinate value was specified. 

An invalid rectangle parameter was specified. 
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GpiCreateRegion - 
Create Region 


Related Functions 

• GpiCombineRegion 

• GpiDestroyRegion 

• GpiEqualRegion 

• GpiOffsetRegion 

• GpiPaintRegion 

• GpiPtlnRegion 

• GpiQueryRegionBox 

• GpiQueryRegionRects 

• GpiRectlnRegion 

• GpiSetRegion 

Example Code 

This example uses the GpiCreateRegion function to create a region consisting of the union of three 
rectangles. 


Idefine INCL_GPIREGIONS /* Region functions */ 

linclude <os2.h> 

HPS hps; /* presentation space handle */ 

HRGN hrgn; /* handle for region */ 

RECTL arcl [3] = { 100, 100, 200, 200, /* 1st rectangle */ 

150, 150, 250, 250, /* 2nd rectangle */ 

200, 200, 300, 300 }; /* 3rd rectangle */ 


hrgn = GpiCreateRegion(hps, /* presentation space */ 

3L, /* three rectangles */ 

arcl); /* address of array of rectangles */ 
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GpiDeleteBitmap - 
Delete Bit Map 


#define INCL_GPIBITMAPS /* Or use INCL_GPI or INCL_PM. Also in COMMON section 7 


BOOL GpiDeleteBitmap (HBITMAP hbm) 


This function deletes a bit map. 

Parameters 

hbm (HBITMAP) - input 

Handle of the bit map to be deleted. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 

PMERR_INV_HBITMAP An invalid bit-map handle was specified. 

PMERR_BITMAP_IS_SELECTED An attempt was made to delete a bit map while it was 

selected into a device context. 

PMERR_HBITMAP_BUSY An internal bit map busy error was detected. The bit map 

was locked by one thread during an attempt to access it 
from another thread. 


Remarks 

There are restrictions on the use of this function while generating a metafile or a PM Q STD print 
file; see “Metafile Restrictions” on page G-1. 


Related Functions 

• GpiBitBIt 

• GpiCreateBitmap 

• GpiDrawBits 

• GpiLoadBitmap 

• GpiQueryBitmapBits 

• GpiQueryBitmapDimension 

• GpiQueryBitmapHandle 

• GpiQueryBitmapParameters 

• GpiQueryDeviceBitmapFormats 

• GpiSetBitmap 

• GpiSetBitmapBits 

• GpiSetBitmapDimension 

• GpiSetBitmapid 

• GpiWCBitBIt 

• WinDrawBitmap 

• WinGetSysBitmap 
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GpiDeleteBitmap - 
Delete Bit Map 


Example Code 

This example uses the GpiDeleteBitmap function to delete a bit map. The GpiSetBitmap function 
releases the bit map from the presentation space before deleting it. This is needed only if the bit 
map is set in the presentation space. 

Idefine INCL_GPIBITMAPS /* GPI Bit map functions */ 

linclude <os2.h> 

HPS hps; /* presentation space handle */ 

HBITMAP hbm, hbmPrevious; 

hbm = GpiLoadBitmap(hps, 0L, 1, GL, 0L); /* load the bit map */ 
hbmPrevious = GpiSetBitmap(hps, hbm); /* set bit map for PS */ 

/* bit map displayed with GpiBitBlt */ 

GpiSetBitmap(hps, hbmPrevious); /* release bit map from PS */ 

GpiDeleteBitmap (hbm) ; /* delete the bit map */ 
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GpiDeleteElement 
Delete Element 


#define INCL_GPISEGEDITING /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiDeleteEiement (HPS hps) 


This function deletes the element indicated by the element pointer. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 


PMERRINVHPS 

PMERR_PS_BUSY 

PMERR_INV_MICROPS_FUNCTION 

PMERRNOTINRETAINMODE 

PMERRNOCURRENTSEG 

PMERRINVINELEMENT 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An attempt was made to issue a function that is invalid in 
a micro presentation space. 

An attempt was made to issue a segment editing element 
function that is invalid when the actual drawing mode is 
not set to retain 

An attempt has been made to issue 
GpiQueryElementType or GpiQueryElement while there is 
no currently open segment. 

An attempt was made to issue a function invalid inside an 
element bracket. 


Remarks 

The element pointer is set to the element immediately preceding the deleted element. 

If the element pointer has a value of 0 (points that are logically before the first element), nothing is 
deleted and the element pointer is not changed. 

This function is only valid when the drawing mode (see GpiSetDrawingMode) is set to retain (not 
draw-and-retain), and a segment bracket is currently in progress. It is invalid within an element 
bracket. 
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GpiDeleteElement - 
Delete Element 


Related Functions 

• GpiBeginElement 

• GpiDeleteElementRange 

• GpiDeleteElementsBetweenLabels 

• GpiElement 

• GpiEndElement 

• GpiLabel 

• GpiOffsetElementPointer 

• GpiQueryElement 

• GpiQueryElementPointer 

• GpiQueryElementType 

• GpiSetElementPointer 

• GpiSetElementPointerAtLabel 

Example Code 

This example uses the GpiDeleteElement function to delete the third element from the previously 
created segment 2. 

Idefine INCL_GPI SEGEDITING 
linclude <os2.h> 

HPS hps; 

GpiOpenSegment(hps, 2L); 

GpiSetElementPointer (hps, 3L); 

Gpi Del eteEl ement (hps ) ; 

GpiCloseSegment(hps) ; 


/* GPI Segment Edit functions */ 


/* open segment #2 


7 


/* move to third element */ 
/* delete element */ 
/* close the segment */ 
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GpiDeleteElementRange 
Delete Element Range 


#define INCL_GPISEGEDITING /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiDeleteElementRange (HPS hps, LONG IFIrstElement, LONG ILastElement) 


This function deletes all elements between, and including, the elements indicated by the specified 
element numbers. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

IFIrstElement (LONG) - input 

Number of the first element to be deleted. 

ILastElement (LONG) - input 

Number of the last element to be deleted. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 


PMERRJNVHPS 

PMERRPSBUSY 

PMERRINVMICROPSFUNCTION 

PMERRNOTINRETAINMODE 

PMERRNOCURRENTSEG 

PMERRINVJNELEMENT 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An attempt was made to issue a function that is invalid in 
a micro presentation space. 

An attempt was made to issue a segment editing element 
function that is invalid when the actual drawing mode is 
not set to retain 

An attempt has been made to issue 
GpiQueryElementType or GpiQueryElement while there is 
no currently open segment. 

An attempt was made to issue a function invalid inside an 
element bracket. 


Remarks 

If either element number is outside the range of the current segment, it is set to the nearest valid 
value. 

When this function has finished, the element pointer is set to the element immediately preceding the 
deleted element or elements. 

This function is only valid when the drawing mode (see GpiSetDrawingMode) is set to retain (not 
draw-and-retaln), and a segment bracket is currently in progress. It is not valid within an element 
bracket. 
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GpiDeleteElementRange - 
Delete Element Range 


Related Functions 

• GpiBeginElement 

• GpiDeleteElement 

• GpiDeleteElementsBetweenLabels 

• GpiElement 

• GpiEndElement 

• GpiLabel 

• GpiOffsetElementPointer 

• GpiQueryElement 

• GpiQueryElementPointer 

• GpiQueryElementType 

• GpiSetElementPointer 

• GpiSetElementPointerAtLabel 

Example Code 

This example uses the GpiDeleteElementRange function to delete the second through fifth elements 
in the previously created segment 2. 

Idefine INCL_GPISEGEDITING /* GPI Segment Edit functions */ 
linclude <os2.h> 

HPS hps; 

GpiOpenSegment(hps, 2L); /* open segment #2 */ 

GpiDeleteElementRange (hps, 2L, 5L);/* delete elements 2 thru 5 */ 

GpiCloseSegment(hps) ; /* close the segment */ 
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GpiDeleteElementsBetweenLabels - 
Delete Elements Between Labels 


#define INCL_GPISEGEDITING /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiDeleteElementsBetweenLabels (HPS bps, LONG IFirstLabel, LONG ILastLabel) 


This function deletes all elements between, but not including, the elements found to contain the 
indicated labels. 

Parameters 

bps (HPS) - input 

Presentation-space handle. 

IFirstLabel (LONG) - input 

Label marking the start of the elements to be deleted. 

ILastLabel (LONG) - input 

Label marking the end of the elements to be deleted. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 


PMERRINVHPS 

PMERR_PS_BUSY 

PMERRINVMICROPSFUNCTION 

PMERRNOTINRETAINMODE 

PMERRNOCURRENTSEG 

PMERRINVJNELEMENT 

PMERRLABELNOTFOUND 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An attempt was made to issue a function that is invalid in 
a micro presentation space. 

An attempt was made to issue a segment editing element 
function that is invalid when the actual drawing mode is 
not set to retain 

An attempt has been made to issue 
GpiQueryElementType or GpiQueryElement while there is 
no currently open segment. 

An attempt was made to issue a function invalid inside an 
element bracket. 

The specified element label did not exist. 


Remarks 

The search for IFirstLabel and ILastLabel is performed separately, and starts from the element 
pointed to by the current element pointer. 

See also: 

• GpiSetElementPointer 

• GpiSetElementPointerAtLabel. 

If either label cannot be found between the current element pointer location and the end of the 
segment, an error is generated and no deletion occurs. 
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GpiDeleteElementsBetweenLabels - 
Delete Elements Between Labels 


On completion, the element pointer is set to the element immediately preceding the deleted 
elements. 

This function is only valid when the drawing mode (see GpiSetDrawingMode) is set to retain (not 
draw-and-retaln), and a segment bracket is currently in progress. It is not valid within an element 
bracket. 

Related Functions 

• GpiBeginElement 

• GpiDeleteElement 

• GpiDeleteElementRange 

• GpiElement 

• GpiEndElement 

• GpiLabel 

• GpiOffsetElementPointer 

• GpiQueryElement 

• GpiQueryElementPointer 

• GpiQueryElementType 

• GpiSetElementPointer 

• GpiSetElementPointerAtLabel 

Example Code 

This example uses the GpiDeleteElementsBetweenLabels function to delete the elements between, 
but not including, the elements having the labels 1 and 2. 

Idefine INCL_GPISEGEDITING /* GPI Segment Edit functions */ 
linclude <os2.h> 

HPS hps; 

GpiOpenSegment(hps, 2L); /* open segment #2 */ 

/* delete elements between 1 and 2 */ 

GpiDeleteElementsBetweenLabels (hps, 1L, 2L); 

GpiCloseSegment(hps) ; /* close the segment */ 
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GpiDeleteMetaFile 
Delete Metafile 


#define INCL_GPIMETAFILES /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiDeleteMetaFile (HMF hmf) 


This function deletes a metafile. 

Parameters 

hmf (HMF) - input 
Metafile handle. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

An invalid metafile handle was specified. 

An attempt has been made to access a metafile that is in 
use by another thread. 

The maximum number of metafiles allowed for a given 
process was exceeded. 


Possible returns from WinGetLastError 

PMERRINVHMF 
PMERRMET AFILEINUSE 

PMERRTOOMANYMET AFILESINUSE 


Remarks 

This function deletes access to the specified memory metafile and makes the metafile handle invalid. 


Related Functions 

• GpiCopyMetaFile 

• GpiLoadMetaFile 

• GpiPlayMetaFile 

• GpiQueryMetaFileBits 

• GpiQueryMetaFileLength 

• GpiSaveMetaFile 

• GpiSetMetaFileBits 
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GpiDeleteMetaFile - 
Delete Metafile 


Example Code 

This example uses GpiDeleteMetaFile to delete a metafile previously loaded with GpiLoadMetaFile. 


Idefine I NCL_GP IMETAFI LES /* Metafile functions */ 
linclude <os2.h> 

BOOL fSuccess; /* success indicator */ 
HMF hmf; /* metafile handle */ 
HAB hab; /* anchor block handle */ 


/* loads metafile from disk */ 

hmf = GpiLoadMetaFile(hab, "sample. met") ; 


fSuccess = GpiDeleteMetaFile(hmf); 
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GpiDeletePalette 
Delete Palette 


^define INCL_GPILOGCOLORTABLE /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiDeletePalette (HPAL hpal) 


This function deletes a color palette. 

Parameters 

hpal (HPAL) - input 
Palette handle. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRJNV HPAL An invalid color palette handle was specified. 

PMERR_PALETTE_SELECTED Color palette operations cannot be performed on a 

presentation space while a palette is selected. 

PMERR_PALETTE_BUSY An attempt has been made to reset the owner of a palette 

when it was busy. 


Remarks 

The palette must not be currently selected into a presentation space (see GpiSelectPalette). 


Related Functions 

• GpiAnimatePalette 

• GpiCreatePalette 

• GpiQueryPalette 

• GpiQueryPalettelnfo 

• GpiSelectPalette 

• GpiSetPaletteEntries 

• WinRealizePalette 
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GpiDeletePalette - 
Delete Palette 


Example Code 

This example uses GpiDeletePalette to delete the color palette currently associated with the 
presentation space, which is determined using GpiQueryPalette. 


Idefine I NCL_GP I LOGCOLORTABLE /* Color Table functions */ 

linclude <os2.h> 


BOOL 

fSuccess; 

/* success indicator 

*/ 

HPAL 

hpal ; 

/* palette handle 

*/ 

HPS 

hps; 

/* Presentation-space handle 

*/ 


/* get handle of currently associated palette */ 
hpal = GpiQueryPalette(hps) ; 

/* delete palette */ 

fSuccess = GpiDeletePalette(hpal); 
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GpiDeleteSegment 
Delete Segment 


#define INCL_GPISEGMENTS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiDeleteSegment (HPS hps, LONG ISegld) 


This function deletes a retained segment. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

ISegld (LONG) - input 
Segment identifier. 

The identifier of the segment to be deleted; it must be greater than 0. 

Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRINVHPS 
PMERRPSBUSY 

PMERRINVSEGNAME 
PMERRINVMICROPSFUNCTION 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid segment identifier was specified. 

An attempt was made to issue a function that is invalid in 
a micro presentation space. 


Remarks 

If the segment is open when it is deleted, there is no open segment after this function. In this 
instance, processing as described for GpiCloseSegment is performed. 

If the segment is in the segment chain, it is removed from the chain. 

This function deletes only a retained segment. 

Note: In draw drawing mode (see GpiSetDrawingMode), the identifier of the current segment is not 
remembered, so it is not recognized if specified as the ISegid parameter. 
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GpiDeleteSegment - 
Delete Segment 


Related Functions 

• GpiCallSegmentMatrix 

• GpiCloseSegment 

• GpiCorrelateSegment 

• GpiDeleteSegments 

• GpiDrawSegment 

• GpiErrorSegmentData 

• GpiOpenSegment 

• GpiQuerylnitialSegmentAttrs 

• GpiQuerySegmentAttrs 

• GpiQuerySegmentNames 

• GpiQuerySegmentPriority 

• GpiSetlnitialSegmentAttrs 

• GpiSetSegmentAttrs 

• GpiSetSegmentPriority 

Example Code 

This example uses the GpiDeleteSegment function to delete segment 4, previously created by 
GpiOpenSegment. 


Idefine INCL_GPISEGMENTS /* Segment functions */ 
finclude <os2.h> 

HPS hps; /* presentation space handle */ 
POINTL ptl Start = { 0, 0 }; /* first vertex */ 
POINTL ptlTrianglef] = { 100, 100, 200, 0, 0, 0 }; /* vertices */ 

GpiOpenSegment (hps, 4L); /* open the segment */ 
GpiMove(hps, &ptlStart); /* move to start point (0, 0) */ 
GpiPolyLine(hps, 3L, ptlTriangle) ; /* draw triangle */ 
GpiCloseSegment(hps) ; /* close the segment */ 


GpiDeleteSegment (hps, 4L); /* delete segment #4 */ 
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GpiDeleteSegments 
Delete Segments 


#define INCL_GPISEGMENTS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiDeleteSegments (HPS hps, LONG IFirstSegment, LONG ILastSegment) 


This function deletes all segments in the given identifier range. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

IFirstSegment (LONG) - input 

First identifier in the range; it must be greater than 0. 

ILastSegment (LONG) - input 

Last identifier in the range; it must be greater than 0. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid segment identifier was specified. 

An attempt was made to issue a function that is invalid in 
a micro presentation space. 


Possible returns from WinGetLastError 

PMERRJNVHPS 

PMERRPSBUSY 

PMERRJNVSEGNAME 

PMERRINVMICROPSFUNCTION 


Remarks 

IFirstSegment and ILastSegment can have the same value, in which instance, only this segment is 
deleted. If IFirstSegment is greater than ILastSegment only the segment with identifier IFirstSegment 
is deleted. 

If one of the segments deleted is the currently open segment, there is no open segment after this 
function. In this instance, processing as described for GpiCloseSegment is performed. If any of the 
segments are in the segment chain, they are removed from the chain. 

This function only deletes retained segments. 

Note: In draw drawing mode (see GpiSetDrawingMode), the identifier of the current segment is not 
remembered, so it is not recognized if it occurs within the range of specified identifiers. 
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GpiDeleteSegments - 
Delete Segments 


Related Functions 

• GpiCallSegmentMatrix 

• GpiCloseSegment 

• GpiCorrelateSegment 

• GpiDeleteSegment 

• GpiDrawSegment 

• GpiErrorSegmentData 

• GpiOpenSegment 

• GpiQuerylnitialSegmentAttrs 

• GpiQuerySegmentAttrs 

• GpiQuerySegmentNames 

• GpiQuerySegmentPriority 

• GpiSetlnitialSegmentAttrs 

• GpiSetSegmentAttrs 

• GpiSetSegmentPriority 

Example Code 

This example uses the GpiDeleteSegments function to delete segments 4 through 6, created by 


GpiOpenSegment. 

fdefine INCL_GPISEGMENTS /* Segment functions */ 

linclude <os2.h> 

HPS hps; /* presentation space handle */ 

GpiOpenSegment (hps, 4L); /* open segment 4 */ 

GpiCloseSegment(hps) ; /* close the segment */ 

GpiOpenSegment(hps, 5L); /* open segment 5 */ 

GpiCloseSegment(hps) ; /* close the segment */ 

GpiOpenSegment (hps, 6L); /* open segment 6 */ 

GpiCloseSegment (hps) ; /* close the segment */ 


GpiDeleteSegments (hps, 4L, 6L); /* delete segments 4 through 6 */ 
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GpiDeleteSetld - 
Delete Set Identifier 


#define INCL_GPILCIDS /* Or use INCL_GPI or INCL_PM 7 


BOOL GpiDeleteSetld (HPS hps, LONG ILcid) 


This function deletes a logical font or bit-map tag. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

ILcid (LONG) - input 
Local identifier. 

The local identifier (Icid) for the object. 

If LCIDALL is specified, all logical fonts are deleted, and all bit-map tagging is removed. If 
LCID DEFAULT or LCID ALL is specified, the original default font is restored if it has been 
changed (see GpiCreateLogFont). 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 


PMERRINVHPS 

PMERRPSBUSY 

PMERRJNVSETID 

PMERRSETIDNOTFOUND 

PMERRSETIDINUSE 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid setid parameter was specified. 

An attempt was made to delete a setid that did not exist. 

An attempt was made to specify a setid that was already 
in use as the currently selected character, marker or 
pattern set. 


Remarks 

If the object is a logical font, it is deleted, and is no longer available for use. If the object is a bit 
map, it is no longer tagged with the local identifier; the bit map is not deleted and its handle remains 
valid. 


In either instance, the ILcid is released and is now available for reuse, unless the object is currently 
selected (as the current character, pattern, or marker set), in which instance an error is raised. 

If this function occurs within a path definition when the drawing mode (see GpiSetDrawingMode) is 
retain or draw-and-retain, its effect is not stored with the definition. 

Note: This function must not be used when creating SAA-conforming metafiles; see “Metafile 
Restrictions” on page G-1. 
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GpiDeleteSetld - 
Delete Set Identifier 


Related Functions 

• GpiCreateLogFont 

• GpiLoadFonts 

• GpiQueryFontMetrics 

• GpiQueryFonts 

• GpiQueryKerningPairs 

• GpiQueryNumberSetlds 

• GpiQuerySetlds 

• GpiQueryWidthTable 

• GpiUnloadFonts 

• GpiSetBitmapId 

• GpiSetCharSet 

Example Code 

This example uses the GpiDeleteSetld function to delete a logical font. The GpiSetCharSet function 
is required only if the logical font is the current font for the presentation space. 

Idefine INCL_GPILCIDS /* Font functions */ 

Idefine INCL_GPI PRIMITIVES /* GPI primitive functions */ 

# include <os2.h> 

HPS hps; /* presentation space handle */ 

FATTRS fat; 

/* create and set the font */ 

GpiCreateLogFont(hps, NULL, 1L, &fat); 

GpiSetCharSet (hps, 1L); 


GpiSetCharSet (hps, OL); /* release the font before deleting */ 

GpiDeleteSetId(hps, 1L); /* delete the logical font */ 
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Gpi Destroy PS - 
Destroy Presentation Space 


#define INCL_GPICONTROL /* Or use INCL_GPI or INCL_PM. Also in COMMON section */ 


BOOL GpiOestroyPS (HPS hps) 


This function destroys the presentation space. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An attempt was made to destroy a presentation or 
associate a presentation space that is still associated 
with a device context. 


Possible returns from WinGetLastError 

PMERRINVHPS 

PMERR_PS_BUSY 

P M E RRPSJSASSOCI ATED 


Remarks 

All resources owned by the presentation space are released, and any subsequent calls that use the 
value of the presentation space handle are rejected. 


Related Functions 

• GpiAssociate 

• GpiCreatePS 

• GpiQueryDevice 

• GpiQueryPS 

• GpiResetPS 

• GpiRestorePS 

• GpiSavePS 

• GpiSetPS 
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GpiDestroyPS - 
Destroy Presentation Space 


Example Code 

This example uses the GpiDestroyPS function to destroy the presentation space associated with a 
memory device context. 


Idefine INCL_GPICONTROL /* GPI control Functions */ 
fdefine INCL_DEV /* Device Function definitions */ 
linclude <os2.h> 

HAB hab; /* Anchor-block handle */ 
HPS bps; /* Target presentation-space handle */ 
HDC hdc; /* Device-context handle */ 
DEVOPENSTRUC dop; /* context data structure */ 
SIZEL page = { 0, 0 }; /* page size (use same as device) */ 


/* Create the memory device context and presentation space. */ 

hdc = DevOpenDC(hab, 0D_MEM0RY , 5L, ( PDE VOPENDATA) &dop , NULLHANDLE); 

hps = GpiCreatePS(hab, hdc, &page, PU_PELS|GPIT_MICRO|GPIA_ASSOC) ; 


GpiAssociate(hps, NULLHANDLE); /* disassociate device context */ 
GpiDestroyPS(hps) ; /* destroys presentation space */ 

DevCloseDC(hdc) ; /* closes device context */ 
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#define INCL_GPIREGIONS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiDestroyRegion (HPS hps, HRGN hrgn) 


This function destroys a region. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

The region must be owned by the device identified by the currently associated device context. 

hrgn (HRGN) - input 

Handle of region to be destroyed. 

If this is NULLHANDLE, the call takes no action, and completes without error. 

Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRJNVHPS 
PMERRPSBUSY 

PMERRINVHRGN 
PMERRREGIONISCLIPREGION 

PMERRHRGNBUSY 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid region handle was specified. 

An attempt was made to perform a region operation on a 
region that is selected as a clip region. 

An internal region busy error was detected. The region 
was locked by one thread during an attempt to access it 
from another thread. 


Remarks 

This function cannot be used to destroy the clip region; the clip region must first be deselected with 
GpiSetClipRegion. 
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Destroy Region 


Related Functions 

Prerequisite Functions 

• GpiSetClipRegion(if the region to be destroyed is a clip region) 

Other Related Functions 

• GpiCombineRegion 

• GpiCreateRegion 

• GpiEqualRegion 

• GpiOffsetRegion 

• GpiPaintRegion 

• GpiPtlnRegion 

• GpiQueryRegionBox 

• GpiQueryRegionRects 

• GpiRectlnRegion 

• GpiSetRegion 

Example Code 

This example uses the GpiDestroyRegion function to destroy a region after drawing a complex 
figure. 

Idefine INCL_GPIREGIONS /* Region functions */ 

linclude <os2.h> 

HPS hps; /* presentation space handle */ 

HRGN hrgn; 

RECTL arcl [3] = { 10,10,20,20,15,15,25,25,20,20,30,30 }; 

hrgn = GpiCreateRegion (hps, 3L, arcl); /* use 3 rectangles */ 

GpiPaintRegion(hps, hrgn); /* paint the region */ 

GpiDestroyRegion(hps, hrgn); /* destroy the region */ 
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#define INCL_GPIBITMAPS /* Or use INCL_GPI or INCL_PM. Also in COMMON section 7 


LONG GpiDrawBits (HPS hpsTarget, PVOID pBits, PBITMAPINF02 pbmi2lnfoTable, 

LONG ICount, PPOINTL aptIPoints, LONG IRop, ULONG flOptions) 


This function draws a rectangle of bits. 

Parameters 

hpsTarget (HPS) - input 

Target presentation-space handle. 

pBits (PVOID) - input 
Source bits. 

The source bits must be in one of the standard bit-map formats. 

pbmi2lnfoTable (PBITMAPINF02) - input 
Bit-map information table. 

This describes the format of the source bits. 

ICount (LONG) - input 
Point count. 

This count must be equal to 4. 

aptIPoints (PPOINTL) - input 
Point array 

Array of ICount points, in the order Txl, Tyl, Tx2, Ty2, Sxl, Syl, Sx2, Sy2. These are: 

Txl.Tyl Specify the bottom left corner of the target rectangle in target world coordinates. 

Tx2,Ty2 Specify the top right corner of the target rectangle in target world coordinates. 

An error occurs if the left coordinate of the target rectangle is greater than the right, 
or if the bottom coordinate is greater than the top. 

Sxl, Syl Specify the bottom left corner of the source rectangle in source device coordinates. 

Sx2,Sy2 Specify the top right corner of the source rectangle in source device coordinates. 

IRop (LONG) - input 

Mixing function required. 

Each plane of the target can be considered to be processed separately. For any pel in a target 
plane, three bits together with the IRop values are used to determine the final value. These are 
the value of that pel in the Pattern (P) and Source (S) data and the initial value of that pel in the 
Target (T) data. For any combination of P, S, and T pel values, the final target value for the pel is 
determined by the appropriate IRop bit value as shown below: 

P S T(initial) T(final) 

0 0 0 

0 0 1 

0 1 0 

0 1 1 

1 0 0 

1 0 1 

1 1 0 

1 1 1 


Index bit 0 (least 
significant) 
Index bit 1 
Index bit 2 
Index bit 3 
Index bit 4 
Index bit 5 
Index bit 6 
Index bit 7 (most 
significant) 
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The index formed as described above determines the mixing required. Mnemonic names are 
available for commonly used mixes: 


R0P_SRCC0PY /* SRC */ 
ROP_SRCPAINT /* SRC OR DST */ 
ROP_SRCAND /* SRC AND DST */ 
ROP_SRCINVERT /* SRC XOR DST */ 
ROP_SRCERASE /* SRC AND NOT(DST) */ 
R0P_N0TSRCC0PY /* NOT (SRC) */ 
ROP_NOTSRCERASE /* NOT(SRC) AND NOT(DST) */ 
R0P_MERGEC0PY /* SRC AND PAT */ 
ROP_MERGEPAINT /* NOT (SRC) OR DST */ 
R0P_PATC0PY /* PAT */ 
ROP_PATPAINT /* NOT(SRC) OR PAT OR DST */ 
R0P_PAT INVERT /* DST XOR PAT */ 
ROP_DSTINVERT /* NOT (DST) */ 
ROP_ZERO /* 0 */ 
ROP_ONE /* 1 */ 


flOptions (ULONG) - input 
Options. 

How eliminated lines or columns are treated if a compression is performed. 

Flags 15 through 31 of flOptions can be used for privately supported modes for particular 
devices. 


BBO_OR 

BBOAND 

BBOJGNORE 


The default value; if compression is necessary, logical-OR eliminated rows or 
columns. This is useful for white on black. 

If compression is necessary, logical-AND eliminated rows or columns. This is 
useful for black on white. 

If compression is necessary, ignore eliminated rows or columns. This is useful 
for color. 


Returns 

Correlation and error indicators: 
GPI_OK Successful 

GPI_HITS Correlate hits 

GPI_ERROR Error. 


Possible returns from WinGetLastError 


PMERRINVHPS 

PMERR_PS_BUSY 

PMERR_INV_LENGTH_OR_COUNT 

PMERR_INV_BITBLT_MIX 

PMERR_INV_BITBLT_STYLE 

PMERRINVCOORDINATE 

PMERR_INV_RECT 

PM ERR_INCORRECT_DC_TYPE 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid length or count parameter was specified. 

An invalid IRop parameter was specified with a GpiBitBIt 
or GpiWCBitBIt function. 

An invalid options parameter was specified with a 
GpiBitBIt or GpiWCBitBIt function. 

An invalid coordinate value was specified. 

An invalid rectangle parameter was specified. 

An attempt was made to perform a bit-map operation on a 
presentation space associated with a device context of a 
type that is unable to support bit-map operations. 
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Remarks 

A rectangle of bit-map image data is copied from storage to a bit map selected into a device context 
associated with the target presentation space. Alternatively, the target presentation space can be 
associated with a device context that specifies a suitable raster device, for example, the screen. An 
error occurs if this device does not support raster operations. 

The source bits must be in one of the standard bit-map formats. 

A rectangle is specified in device coordinates for the source bits, and one in world coordinates for 
the target presentation space. The source rectangle is noninclusive; the left and lower boundaries in 
device space are included, but not the right and upper boundaries. Thus if the bottom left is equal to 
the top right, the rectangle is deemed to be empty. The target rectangle is “inclusive-inclusive”; that 
is, all boundaries are included in the rectangle. 

If the target rectangle, after transformation to device coordinates and adjustment for inclusivity, is 
not the same size as the source rectangle, then stretching or compressing of the data occurs. 
flOptions specifies how eliminated rows or columns of bits are to be treated if compression occurs. 
Note that the pattern data is never stretched or compressed. 

These current attributes of the target presentation space are used (other than for converting between 
monochrome and color, as described below): 

• Area color 

• Area background color 

• Pattern set 

• Pattern symbol. 

The color values are used in conversion between monochrome and color data. This is the only 
format conversion performed by this function. The conversions are: 

• Output of a monochrome pattern to a color device 

In this instance the pattern is converted first to a color pattern, using the current area colors: 

- source Is -> area foreground color 

- source Os -*■ area background color. 

• Copying from a monochrome bit map to a color bit map (or device) 

The source bits are converted as follows: 

- source Is -» image foreground color 

- source Os -» image background color. 

• Copying from a color bit map to a monochrome bit map (or device) 

The source bits are converted as follows: 

- source nonzeros -*• image foreground color 

- source Os -*• image background color. 

If the mix (/flop) does not call for a pattern, the pattern set and pattern symbol are not used. 

Neither the source nor the pattern is required when a bit map, or part of a bit map, is to be cleared to 
a particular color. 

If the mix does require both source and pattern, a three-way operation is performed. 

If a pattern is required, dithering may be performed for solid patterns in a color that is not available 
on the device. See GpiSetPattern. 
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This function can cause immediate drawing, or be retained in segment store, or both of these, 
depending upon the drawing mode (see GpiSetDrawingMode). If the function is retained in segment 
store, the storage identified by the pBits and pbmi2lnfoTable parameters must not be changed or 
freed by the application while the segment containing the function can still be drawn. However, if a 
metafile is generated and no further drawing is needed, this does not apply, as the information is 
encaptured in the metafile. 

Note: There are restrictions on the use of this function when creating SAA-conforming metafiles; 
see “Metafile Restrictions” on page G-1. 

Related Functions 

• GpiBitBIt 

• GpiCreateBitmap 

• GpiDeleteBitmap 

• GpiLoadBitmap 

• GpiQueryBitmapBits 

• GpiQueryBitmapDimension 

• GpiQueryBitmapHandle 

• GpiQueryBitmapParameters 

• GpiQueryDeviceBitmapFormats 

• GpiSetBitmap 

• GpiSetBitmapBits 

• GpiSetBitmapDimension 

• GpiSetBitmapid 

• GpiWCBitBIt 

• WinDrawBitmap 

• WinGetSysBitmap 

Graphic Elements and Orders 

Element Type: OCODE_GBBLT 
Order: Bitblt 
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Example Code 

This example uses GpiDrawBits to draw a rectangle of bits. The bit map was previously placed in 
application memory using GpiQueryBitmapBits; when the stored image is displayed, it will be a 
compressed copy (ROP_SRCCOPY) of the source bit map (note the difference between the target and 
source rectangle sizes), with eliminated rows/columns ignored (BBOJGNORE) when compression 
takes place. 


Idefine INCL_GPIBITMAPS /* Bit map functions */ 
linclude <os2.h> 

HPS hps; /* presentation-space handle */ 
PBYTE pb; /* bit-map image data */ 
BITMAPINF02 pbmi ; /* bit-map information table */ 
LONG lHits; /* correlation/error indicator */ 
LONG IScan; /* number of lines scanned */ 
/* target and source rectangles */ 


POINTL aptl Points [4] ={ 300, 400, 350, 450, 0, 0, 100, 100 }; 

/* scan and transfer bit map to application storage */ 
pbmi .cbFix = 16L; 
pbmi.cPlanes = 1; 
pbmi .cBitCount = 4; 

IScan = GpiQueryBitmapBits (hps, 0L, 100L, pb, &pbmi); 


/* draw stored rectangle bit map */ 

lHits = GpiDrawBits (hps, (VOID *)pb, &pbmi, 4L, 

aptl Points, R0P_SRCC0PY, BBOJGNORE); 
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#define INCL_GPISEGMENTS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiDrawChain (HPS hps) 


This function draws the segments that are in the segment chain. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERR_INV_HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_MICROPS_FUNCTION An attempt was made to issue a function that is invalid in 

a micro presentation space. 

Remarks 

The segments drawn are all of the retained segments that have the ATTR_CHAINED segment 
attribute (see GpiSetlnitialSegmentAttrs), together with all of the unchained segments that are called 
from them. 

The drawing operation is controlled by the calls set by the draw controls (see GpiSetDrawControl), 
except for the correlate control. If there is not a segment open at the time of the draw, and this 
function is followed by primitives or attributes, without first opening a segment, the processing is as 
described for GpiCloseSegment. 

If a segment is already open at the time of the draw, GpiCloseSegment processing is not performed 
at the completion of the draw (except that any unclosed path or area is abandoned with an error). In 
this instance, if the open segment is the last one drawn (and no dynamic segments had to be drawn), 
attributes and other parameters are in the correct state to continue drawing in any drawing mode. 

Dynamic segments are not drawn if they are found while processing the segment chain. However, 
depending on the setting of DCTL DYNAMIC (see GpiSetDrawControl), they may be removed before, 
and drawn after, the operation. 

It may be necessary to ensure that attributes, model transform, current position, and viewing limits 
are reset to their default values, before processing the chain. This can be done by ensuring that the 
first segment to be drawn does not have the ATTR FASTCHAIN attribute (see 
GpiSetlnitialSegmentAttrs), or by issuing GpiResetPS before the GpiDrawChain. The latter method 
also resets the clip path to no clipping, which may also be necessary. 
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It is an error to issue this function while any of these brackets are open: 

• Area bracket 

• Path bracket 

• Element bracket. 

Related Functions 

• GpiDrawDynamics 

• GpiDrawFrom 

• GpiDrawSegment 

• GpiErase 

• GpiQueryDrawControl 

• GpiQueryDrawingMode 

• GpiQueryStopDraw 

• GpiRemoveDynamics 

• GpiSetDrawControl 

• GpiSetDrawingMode 

• GpiSetStopDraw 

Example Code 

This function uses GpiDrawChain to draw the two chained segments. 

Idefine I NCL_GP I SEGMENTS /* Segment functions */ 

linclude <os2.h> 

BOOL fSuccess;- /* success indicator */ 

HPS hps; /* presentation-space handle */ 

/* The chaining attribute is switched on */ 
GpiSetInitialSegmentAttrs(hps, ATTR_CHAINED, ATTR_0N); 

/* two chained segments are defined */ 

GpiOpenSegment(hps, 1L); 


Gpi Cl oseSegment (hps ) ; 
GpiOpenSegment(hps, 2L); 

Gpi Cl oseSegment (hps) ; 

/* draw the segment chain */ 
fSuccess = GpiDrawChain (hps) ; 
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#define INCL_GPISEGMENTS /* Or use INCL_GPI or INCL_PM 7 


BOOL GpiDrawDynamics (HPS hps) 


This function redraws the dynamic segments in, or called from, the segment chain. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 


PMERRINVHPS 

PMERR_PS_BUSY 

PMERR_INV_MICROPS_FUNCTION 

P M E R R_IN V_FOR_THIS_DC_TYPE 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An attempt was made to issue a function that is invalid in 
a micro presentation space. 

An attempt has been made to issue GpiRemoveDynamics 
or GpiDrawDynamics to a presentation space associated 
with a metafile device context. 


Remarks 

Dynamic segments are those segments in the segment chain that have the ATTR_DYNAMIC segment 
attribute (see GpiSetlnitialSegmentAttrs). It is preferable to position dynamic segments at the start of 
the segment chain. 

Dynamic segments can either be drawn with this function, or by setting the DCTL DYNAMIC draw 
control (see GpiSetDrawControl), and issuing one of the other GpiDraw... calls. 

If there is no range set by a previous GpiRemoveDynamics, all dynamic segments are redrawn by 
GpiDrawDynamics). However, if GpiRemoveDynamics specified a range in the segment chain, the 
redraw is restricted to the dynamic segments that are in, or called from, the selected range. (See 
GpiRemoveDynamics). 

Note: The redraw is controlled by the calls set by previous calls to GpiSetDrawControl. 

The “stop draw” condition can be set (from another thread) while GpiDrawDynamics is in 
progress. This is useful in responding to a new position by setting this condition, and then 
clearing it and redrawing at the new position. 

If “Erase before draw” is set ON (see GpiSetDrawControl), the presentation space is erased before 
the redraw. 

It may be necessary to ensure that attributes, model transform, current position, and viewing limits 
are reset to their default values, before processing the segments. This can be done either by 
ensuring that the first dynamic segment to be drawn does not have the ATTR FASTCHAIN attribute 
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(see GpiSetlnitialSegmentAttrs), or by issuing GpiResetPS before the GpiDrawDynamics. The latter 
method also resets the clip path to no clipping, which may also be necessary. 

If this function is followed by primitives or attributes, without first opening a segment, the processing 
is as described for GpiCloseSegment. In particular, note that during GpiDrawDynamics, the system 
forces the foreground mix to FM_XOR and the background mix to BMLEAVEALONE. It may be 
necessary to set one or both of these before starting to draw. 


Related Functions 

• GpiDrawChain 

• GpiDrawFrom 

• GpiDrawSegment 

• GpiErase 

• GpiGetData 

• GpiPutData 

• GpiQueryDrawControl 

• GpiQueryDrawingMode 

• GpiQueryStopDraw 

• GpiRemoveDynamics 

• GpiSetDrawControl 

• GpiSetDrawingMode 

• GpiSetlnitialSegmentAttrs 

• GpiSetSegmentAttrs 

• GpiSetStopDraw 

Example Code 

This example uses GpiDrawDynamics to redraw the two previously defined dynamic chained 
segments. 

Idefine INCL_GPISEGMENTS /* Segment functions */ 

linclude <os2.h> 

BOOL f Success; /* success indicator */ 

HPS hps; /* presentation-space handle */ 

/* The chaining attribute is switched on */ 

GpiSetlnitialSegmentAttrs (hps, ATTR_CHAINED | ATTR_DYNAMIC, 

ATTR_0N) ; 

/* two dynamic chained segments are defined */ 

GpiOpenSegment(hps, 1L); 


GpiCloseSegment(hps) ; 
GpiOpenSegment(hps, 2L); 

GpiCloseSegment(hps) ; 

/* draw the dynamic segment chain */ 
fSuccess = GpiDrawDynamics (hps) ; 
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#define INCL_GPISEGMENTS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiDrawFrom (HPS hps, LONG IFirstSegment, LONG ILastSegment) 


This function draws a section of the segment chain. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

IFirstSegment (LONG) - input 

First segment to be drawn; it must be greater than 0. 

ILastSegment (LONG) - input 

Last segment to be drawn; it must be greater than 0. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRJNVHPS 
PMERRPSBUSY 

PMERR_INV_MICROPS_FUNCTION 

PMERRSEGNOTFOUND 
PMERRSEGNOTCHAINED 

PMERRINVSEGNAME 

Remarks 

Drawing starts at the segment identified by IFirstSegment and includes all chained segments (those 
with the ATTR CHAINED segment attribute, see GpiSetlnitialSegmentAttrs), and the segments called 
from them, up to, and including, the segment identified by ILastSegment. 

The drawing operation is controlled by the calls set by the draw controls (see GpiSetDrawControl), 
except for the correlate control. 

If there is not a segment open at the time of the draw, and this function is followed by primitives or 
attributes, without first opening a segment, the processing is as described for GpiCloseSegment. 

If a segment is already open at the time of the draw, GpiCloseSegment processing is not performed 
at the completion of the draw (except that any unclosed path or area is terminated with an error). In 
this instance, if the open segment is the last one drawn (and no dynamic segments had to be drawn), 
attributes and other parameters are in the correct state to continue drawing in any drawing mode. 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An attempt was made to issue a function that is invalid in 
a micro presentation space. 

The specified segment identifier did not exist 

An attempt was made to issue GpiDrawFrom, 
GpiCorrelateFrom or GpiQuerySegmentPriority for a 
segment that was not chained. 

An invalid segment identifier was specified. 
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Dynamic segments are not drawn if they are found while processing the segment chain. However, 
depending on the setting of DCTL_DYNAMIC (see GpiSetDrawControl), they may be removed before, 
and drawn after, the operation. If this happens, then all dynamic segments are involved, whether 
they occur within the range specified or not. 

It may be necessary to ensure that attributes, model transform, current position, and viewing limits 
are reset to their default values, before processing the segments. This can be done either by 
ensuring that the first segment to be drawn does not have the ATTR_FASTCHAIN attribute (see 
GpiSetlnitialSegmentAttrs), or by issuing GpiResetPS before the GpiDrawFrom. The latter method 
also resets the clip path to no clipping, which may also be necessary. 

It is an error to issue this function while any of these brackets are open: 

• Area bracket 

• Path bracket 

• Element bracket. 

If IFirstSegment does not exist, or is not in the segment chain, an error is raised. If the ILastSegment 
does not exist, or is not in the chain, or is chained before the IFirstSegment, no error is raised, and 
processing continues to the end of the chain. 


Related Functions 

• GpiDrawChain 

• GpiDrawDynamics 

• GpiDrawSegment 

• GpiErase 

• GpiGetData 

• GpiPutData 

• GpiQueryDrawControl 

• GpiQueryDrawingMode 

• GpiQueryStopDraw 

• GpiRemoveDynamics 

• GpiSetDrawControl 

• GpiSetDrawingMode 

• GpiSetStopDraw 

Example Code 

This example uses the GpiDrawFrom function to draw all segments in the picture chain between and 
including the segments 1 and 4. 

fdefine INCL_GPISEGMENTS /* Segment functions */ 

linclude <os2.h> 

HPS hps; /* presentation space handle */ 

GpiDrawFrom(hps, 1L, 4L); 
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#define INCL_GPISEGMENTS /* Or use INCL_GPI or INCL_PM 7 


BOOL GpiDrawSegment (HPS hps, LONG ISegment) 


This function draws the specified segment. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

ISegment (LONG) - input 

Segment to be drawn; it must be greater than 0. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRINVHPS 
PMERRPSBUSY 

PMERRJNVMICROPSFUNCTION 

PMERRSEGNOTFOUND 
PMERR_INV_SEG_NAME 

Remarks 

The drawing operation is controlled by the calls set by the draw controls (see GpiSetDrawControl), 
except for the correlate control. 

If there is not a segment open at the time of the draw, and this function is followed by primitives or 
attributes, without first opening a segment, the processing is as described for GpiCloseSegment. 

If a segment is already open at the time of the draw, GpiCloseSegment processing is not performed 
at the completion of the draw (except that any unclosed path or area is abandoned with an error). In 
this instance, if the open segment is the segment specified in ISegment, and no dynamic segments 
had to be drawn, then attributes and other parameters are in the correct state to continue drawing in 
any drawing mode. 

Depending on the setting of DCTL_DYNAMIC (see GpiSetDrawControl), all of the dynamic segments 
in the chain may be removed before, and drawn after, the specified segment is drawn. (Note that if 
the specified segment is itself dynamic, it is only drawn in this way.) 

This function differs from the other GpiDraw... calls, in that the segment to be drawn need not be a 
chained segment. 

It may be necessary to ensure that attributes, model transform, current position, and viewing limits 
are reset to their default values, before processing the segment. This can be done either by 
ensuring that the segment does not have the ATTR FASTCHAIN attribute (see 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An attempt was made to issue a function that is invalid in 
a micro presentation space. 

The specified segment identifier did not exist 

An invalid segment identifier was specified. 
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GpiSetlnitialSegmentAttrs), or by issuing GpiResetPS before the GpiDrawSegment. The latter 
method also resets the clip path to no clipping, which may also be necessary. 

It is an error to issue this function while any of these brackets are open: 

• Area bracket 

• Path bracket 

• Element bracket. 


Related Functions 

• GpiDrawChain 

• GpiDrawDynamics 

• GpiDrawFrom 

• GpiErase 

• GpiErrorSegmentData 

• GpiQueryDrawControl 

• GpiQueryDrawingMode 

• GpiQueryStopDraw 

• GpiRemoveDynamics 

• GpiSetDrawControl 

• GpiSetDrawingMode 

• GpiSetStopDraw 


Example Code 

This example uses the GpiDrawSegment function to draw segment 4. 


Idefine INCL_GPISEGMENTS /* Segment functions */ 
linclude <os2.h> 

HPS hps; /* presentation space handle */ 
POINTL ptl Start = { 0, 0 }; /* first vertex */ 
POINTL ptlTriangle[] = { 100, 100, 200, 0, 0, 0 }; /* vertices */ 


GpiOpenSegment(hps, 4L); /* 
GpiMove(hps, &ptl Start); /* 
GpiPolyLine(hps, 3L, ptlTriangle) ; /* 
GpiCloseSegment(hps) ; /* 


open the segment */ 
move to start point (0, 0) */ 
draw triangle */ 
close the segment */ 


GpiDrawSegment (hps, 4L); 


/* draw segment #4 


*/ 
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#define INCL_GPISEGEDITING /* Or use INCL_GPI or INCL_PM */ 


LONG GpiElement (HPS hps, LONG IType, PSZ pszDesc, LONG ILength, PBYTE pbData) 


This function adds a single element to the current segment. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

IType (LONG) - input 

Type to be associated with the element. 

Application-defined elements should have type values in the range X'81xxxxxx' through 
X'FFxxxxxx 1 so as to avoid conflict with system-generated elements. 

pszDesc (PSZ) - input 
Element description. 

This is a variable length character string that is recorded with the element. 

ILength (LONG) - input 

Length of content data for the element. 

This must not be greater than 63KB. 

pbData (PBYTE) - input 
Buffer pointer. 

Element content data. 


Returns 

Correlation and error indicators: 

GPI_OK Successful 

GPI_HITS Correlate hits 

GPI_ERROR Error. 

An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An attempt was made to issue a function that is invalid in 
a micro presentation space. 

An invalid length or count parameter was specified. 

An attempt was made to transfer more than the maximum 
permitted amount of data (64512 bytes) using GpiPutData, 
GpiGetData, or GpiElement. 

An attempt was made to begin a new element while an 
existing element bracket was already open. 


Possible returns from WinGetLastError 

PMERRINVHPS 

PMERRPSBUSY 

PMERRINVMICROPSFUNCTION 

PMERR_INV_LENGTH_OR_COUNT 
PMERR_DAT A_TOO_LONG 

PMERRALREADYINELEMENT 
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GpiElement 

Element 


Remarks 

The element is stored in the current segment if the drawing mode (see GpiSetDrawingMode) is retain 
or draw-and-retain. It is drawn if the drawing mode is draw or draw-and-retain. 

It is an error if the element data contains any begin or end element orders. Similarly, this function is 
not valid within an element bracket. 

Note: No coordinate conversion is performed by this function. The application must ensure that the 
coordinates within the element are in the correct format for the presentation space (see 
GpiCreatePS). 


Related Functions 

• GpiBeginElement 

• GpiDeleteElement 

• GpiDeleteElementRange 

• GpiDeleteElementsBetweenLabels 

• GpiEndElement 

• GpiLabel 

• GpiOffsetElementPointer 

• GpiQueryElement 

• GpiQueryElementPointer 

• GpiQueryElementType 

• GpiSetElementPointer 

• GpiSetElementPointerAtLabel 
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GpiElement - 
Element 


Example Code 

This example uses GpiElement to add a single element to the current segment: an arc starting at the 
current position, passing through (10,10), and ending at (5,5). 

Idefine INCL_GPISEGEDITING /* GPI Segment Edit functions */ 

Idefine INCL_GPISEGMENTS /* Segment functions */ 

Idefine INCL_0RDERS /* Graphical Order Formats */ 

linclude <os2.h> 


LONG 

lHits; 

/* correlation/error indicator 

*/ 

HPS 

hps; 

/* presentation-space handle 

*/ 

LONG 

lType; 

/* element type 

*/ 

char 

pszDesc [4] ; 

/* element description 

*/ 

LONG 

1 Length; 

/* length of element data 

*/ 

LORDER 

pbData; 

/* pointer to element data 

*/ 


0RDERL_GCARC lArcPts = {10L,10L,5L,5L}; /* arc points structure */ 

GpiOpenSegment(hps, 3L); /* opens segment to receive element */ 

/* type is order code for arc at current position (GARC) */ 
lType = 0C0DE_GCARC; 

/* call the element 'Arc' */ 
strcpy(pszDesc, "Arc") ; 

/* length of element data */ 

1 Length = sizeof(LORDER) ; 

/* fill element data structure */ 

pbData.idCode = 0C0DE_GCARC; /* order code: arc at current 

position */ 

pbData.uchLength = sizeof(ORDERL_GCARC) ; 

/* order data contains arc points structure */ 
memcpy(pbData.uchData, lArcPts, sizeof(ORDERL_GCARC)); 

/* add element */ 

lHits = GpiElement(hps, lType, pszDesc, 1 Length, (BYTE *)&pbData); 
GpiCloseSegment(hps) ; /* closes segment that received data */ 
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GpiEndArea 
End Area 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM. Also in COMMON section */ 


LONG GpiEndArea (HPS hps) 


This function ends the construction of a shaded area. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 


Returns 

Correlation and error indicators: 

GPI_OK Successful 

GPI_HITS Correlate hits 

GPI_ERROR Error. 

Possible returns from WinGetLastError 

PMERRJNV HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_NOT_IN_AREA An attempt was made to end an area using GpiEndArea 

or during segment drawing while not In an area bracket. 

PMERR_COORDINATE_OVERFLOW An Internal coordinate overflow error occurred. This can 

occur if coordinates or matrix transformation elements (or 
both) are invalid or too large. 


Remarks 

The construction is started by the GpiBeginArea function. If necessary, a final line is constructed (to 
the starting point of the last figure) to close the area. 

The current position is not changed, unless a closure line has to be drawn, in which case the current 
position is moved to the end point of the line. 
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GpiEndArea - 
End Area 


Related Functions 

Prerequisite Functions 

• GpiBeginArea 

Other Related Functions 

• GpiSetPattern 

• GpiSetPatternRefPoint 

• GpiSetPatternSet 

• GpiPop 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiSetBackColor 

• GpiSetBackMix 

• GpiSetColor 

• GpiSetMix 

Graphic Elements and Orders 

Element Type: OCODE_GEAR 
Order: End Area 

Example Code 

This example uses the GpiEndArea function to end an area bracket. The function draws the area (a 
triangle) by filling the outline with the current fill pattern. 

Idefine INCL_GPI PRIMITIVES /* GPI primitive functions */ 
linclude <os2.h> 

HPS hps; /* presentation space handle */ 

POINTL ptl Start = { 0, 0 }; /* first vertex */ 

POINTL ptlTrianglef] = { 100, 100, 200, 0, 0, 0 }; /* vertices */ 

GpiBeginArea (hps, BA_N0B0UNDARY | BA_ALTERNATE) ; 

GpiMove(hps, &ptl Start); 

GpiPolyLine(hps, 3L, ptlTriangle) ; 

GpiEndArea (hps) ; 
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GpiEndElement 
End Element 


#define INCL_GPISEGEDITING /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiEndElement (HPS hps) 


This function terminates an element started by GpiBeginElement. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERR_INV_HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_NOT_IN_ELEMENT An attempt was made to end an element using 

GpiEndElement or during segment drawing while not in 
an element bracket. 

Related Functions 

Prerequisite Functions 

• GpiBeginElement 

Other Related Functions 

• GpiDeleteElement 

• GpiDeleteElementRange 

• GpiDeleteElementsBetweenLabels 

• GpiElement 

• GpiLabel 

• GpiOffsetElementPointer 

• GpiQueryElement 

• GpiQueryElementPointer 

• GpiQueryElementType 

• GpiSetElementPointer 

• GpiSetElementPointerAtLabel 
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GpiEndElement - 
End Element 


Example Code 

This example uses the GpiEndElement function to end an element bracket. 

Idefine INCL_GPISEGEDITING /* GPI Segment Edit functions */ 
linclude <os2.h> 

HPS hps; /* presentation space handle */ 

POINTL ptlStart = { 0, 0 }; /‘first vertex */ 

POINTL ptlTrianglef] = { 100, 100, 200, 0, 0, 0 }; /* vertices */ 


/* begin the element bracket */ 

GpiBeginElement(hps, 1L, "Triangle"); 

GpiMove(hps, &ptl Start); /* move to start point (0, 0) */ 

GpiPolyLine(hps, 3L, ptlTriangle) ; /* draw triangle */ 

GpiEndElement (hps); /* end element bracket */ 
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GpiEndPath 
End Path 


#define INCL_GPIPATHS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiEndPath (HPS hps) 


This function ends the specification of a path started by GpiBeginPath. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERR_INV_HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_NOT_IN_PATH An attempt was made to end a path using GpiEndPath or 

during segment drawing while not in a path bracket. 

Related Functions 

Prerequisite Functions 

• GpiBeginPath 

Other Related Functions 

• GpiFillPath 

• GpiModifyPath 

• GpiOutlinePath 

• GpiPathToRegion 

• GpiSetClipPath 

• GpiStrokePath 

• GpiSetLineEnd 

• GpiSetLineJoin 

• GpiSetLineType 

• GpiSetLineWidth 

• GpiSetLineWidthGeom 

• GpiPop 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiSetBackColor 

• GpiSetBackMix 

• GpiSetColor 

• GpiSetMix 
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GpiEndPath - 
End Path 


Graphic Elements and Orders 

Element Type: OCODE_GEPTH 


Order: End Path 


Example Code 

This example uses the GpiEndPath function to end a path bracket. When the path bracket is ended, a 
subsequent call to the GpiFillPath function draws and fills the path. 


fdefine INCL_GPIPATHS 
linclude <os2.h> 


/* GPI Path functions 


HPS hps; /* presentation space handle 

POINTL ptl Start = { 0, 0 }; /* first vertex 

POINTL ptlTriangle[] = { 100, 100, 200, 0, 0, 0 }; /* vertices 


*/ 

*/ 

*/ 


GpiBeginPath(hps, 1L); 

GpiMove(hps, SptlStart); 
GpiPolyLine(hps, 2L, ptlTriangle) ; 
GpiCloseFigure(hps) ; 

GpiEndPath (hps) ; 

GpiFillPath(hps, 1L, FPATH_ALTERNATE) ; 


/* start the path bracket */ 
/* move to starting point */ 
/* draw the three sides */ 
/* close the triangle */ 
/* end the path bracket */ 
/* draw and fill the path */ 


Chapter 5. Graphics Functions 5-133 


GpiEqualRegion 
Equal Region 


#define INCL_GPIREGIONS /* Or use INCL_GPI or INCL_PM */ 


LONG GpiEqualRegion (HPS hps, HRGN hrgnSrcl, HRGN hrgnSrc2) 


This function checks whether two regions are identical. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

The regions must be owned by the device identified by the currently associated device context. 

hrgnSrcl (HRGN) - input 
Handle of first region. 

hrgnSrc2 (HRGN) - input 
Handle of second region. 


Returns 

Equality and error indicators: 

EQRGN_NOTEQUAL Not equal 
EQRGN_EQUAL Equal 

EQRGN_ERROR Error. 

An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid region handle was specified. 

An attempt was made to perform a region operation on a 
region that is selected as a clip region. 

An internal region busy error was detected. The region 
was locked by one thread during an attempt to access it 
from another thread. 


Possible returns from WinGetLastError 

PMERRINVHPS 

PMERRPSBUSY 

PMERRINVHRGN 

PMERRREGIONISCLIPREGION 

PMERRHRGNBUSY 


Remarks 

Both regions must be of the same device class. It is invalid if the specified region is currently 
selected as the clip region (by GpiSetClipRegion). 
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GpiEqualRegion - 
Equal Region 


Related Functions 

• GpiCombineRegion 

• GpiCreateRegion 

• GpiDestroyRegion 

• GpiOffsetRegion 

• GpiPaintRegion 

• GpiPtlnRegion 

• GpiQueryRegionBox 

• GpiQueryRegionRects 

• GpiRectlnRegion 

• GpiSetRegion 

• WinEqualRect 

Example Code 

This example uses GpiEqualRegion to create two regions (each consisting of three rectangles), and 
then compares them for equality. 


Idefine 

INCL_GPIREGIONS 

1 /* Region functions 

*/ 

linclude <os2.h> 



LONG 

1 Equality; 

/* equal ity/error indicator 

*/ 

HPS 

hps; 

/* presentation-space handle 

*/ 

HRGN 

hrgnSrcl; 

/* handle for first region 

*/ 

HRGN 

hrgnSrc2; 

/* handle for second region 

*/ 

RECTL arcl [3] = { 100, 

100, 200, 200, /* 1st rectangle 

*/ 


150, 

150, 250, 250, /* 2nd rectangle 

*/ 


200, 

200, 300, 300 }; /* 3rd rectangle 

*/ 


/* create two identical regions comprising three rectangles each*/ 
hrgnSrcl = GpiCreateRegion(hps, 3L, arcl); 
hrgnSrc2 = GpiCreateRegion(hps, 3L, arcl); 

1 Equal i ty = GpiEqualRegion(hps, hrgnSrcl, hrgnSrc2); 
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GpiErase 

Erase 


#define INCL_GPICONTROL /* Or use INCL_GPI or INCL_PM. Also in COMMON section */ 


BOOL GpiErase (HPS hps) 


This function clears the output display of the device context associated with the specified 
presentation space, to the reset color (CLR_BACKGROUND; see GpiSetColor). 

Parameters 

hps (HPS) - input 

Presentation-space handle. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRJNV HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 


Remarks 

This operation is independent of the draw controls; see GpiSetDrawControl. 

The call is subject to all clipping currently in force; that is, clip path, viewing limits, graphics field, 
clip region, and visible region. 

This function does not perform any bounds collection, or correlation. 

Note: This function must not be used when creating metafiles conforming to SAA* guidelines; see 
“Metafile Restrictions” on page G-1. 

Related Functions 

• GpiCreateLogColorTable 

• GpiSetColor 

• GpiSetDrawControl 


• Trademark of IBM Corporation 
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GpiErase - 
Erase 


Example Code 

This example uses the GpiErase function to clear the display before drawing. 

Idefine INCL_GPICONTROL /* GPI control Functions */ 

finclude <os2.h> 

HPS hps; /* presentation space handle */ 

POINTL ptlStart = { 0, 0 }; /* start point */ 

POINTL ptlTriangle[] = { 100, 100, 200, 0, 0, 0 }; /* vertices */ 

GpiErase(hps) ; /* clear the display */ 

GpiMove(hps, &ptl Start) ; /* draw a triangle */ 

GpiPolyLine(hps, 3L, ptlTriangle) ; 
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GpiErrorSegmentData 
Error Segment Data 


#define INCL_GPICONTROL /* Or use INCL_GPI or INCL_PM 7 


LONG GpiErrorSegmentData (HPS hps, PLONG piSegment, PLONG piContext) 


This function returns information about the last error that occurred during a segment drawing 
operation. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

piSegment (PLONG) - output 

Segment in which the error occurred. 

piContext (PLONG) - output 
Context of the error: 

GPIE_SEGMENT The error occurred while processing the contents of a retained segment. 

GPIE_ELEMENT The error occurred while processing the contents of a GpiElement function. 

GPIE_DATA The error occurred while processing the contents of a GpiPutData function. 

Returns 

Position. 

This is either the byte offset or the element number, depending on piContext: 

>0 Position 

GPI_ALTERROR Error. 

Possible returns from WinGetLastError 

PMERRJNV HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_MICROPS_FUNCTION An attempt was made to issue a function that is invalid in 

a micro presentation space. 

Remarks 

The information returned is: 

• The segment name 

• The context 

• The byte offset or element number (depending on the context). 

The byte offset is returned for these contexts: 

• The error occurred within the data of a GpiElement function 

• The error occurred within the data of a GpiPutData function. 

The element number is returned for the segment context. 
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GpiErrorSegmentData - 
Error Segment Data 


Related Functions 

• GpiElement 

• GpiDrawChain 

• GpiDrawDynamics 

• GpiDrawFrom 

• GpiDrawSegment 

• GpiGetData 

• GpiPutData 

• GpiRemoveDynamics 

Example Code 

This example uses GpiErrorSegmentData to query the error context and assigns a variable to the 
returned element number if the context is an element error. 


Idefine INCL_GPICONTROL /* Control functions */ 

finclude <os2.h> 


LONG 

lOff; 

/* 

error or offset/element number 

*/ 

HPS 

hps; 

/* 

presentation-space handle 

*/ 

LONG 

pi Segment ; 

/* 

Segment in which the error occurred 

*/ 

LONG 

pi Context; 

/* 

Context of the error 

*/ 

LONG 

1 El ement ; 

/* 

element number causing error 

*/ 


lOff = GpiErrorSegmentData (hps, &pl Segment, &pl Context); 

if (pi Context = GPIE_ELEMENT) 

1 Element = lOff; 
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GpiExcludeClipRectangle 
Exclude Clip Rectangle 


#define INCL_GPIREGIONS /* Or use INCL_GPI or INCL_PM */ 


LONG GpiExcludeClipRectangle (HPS hps, PRECTL prcIRectangle) 


This function excludes a rectangle from the clipping region. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

prcIRectangle (PRECTL) - input 
Rectangle to be excluded. 

The coordinates are world coordinates. 


Returns 

Complexity of clipping and error indicators. 

The clipping complexity information includes the combined effects of: 

• Clip path 

• Viewing limits 

• Graphics field 

• Clip region 

• Visible region (windowing considerations). 


RGN_NULL 

RGNRECT 

RGNCOMPLEX 

RGNERROR 


Null region 
Rectangular region 
Complex region 
Error. 


Possible returns from WinGetLastError 


PMERRJNV HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_COORDINATE An invalid coordinate value was specified. 

PMERR_INV_RECT An invalid rectangle parameter was specified. 


Remarks 

The boundaries of the rectangle are considered to be part of the interior, so that a point on the 
rectangle boundary is clipped (removed). 

This function creates a clip region if one does not currently exist. The application is responsible for 
freeing this (with GpiOestroyRegion) if it subsequently selects another clip region (see 
GpiSetClipRegion). Any clip region still selected when the device context is closed is automatically 
freed. 

Note: This function must not be used when creating SAA-conforming metafiles; see “Metafile 
Restrictions” on page G-1 . 
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GpiExcludeClipRectangle - 
Exclude Clip Rectangle 


Related Functions 

• GpilntersectClipRectangle 

• GpiOffsetClipRegion 

• GpiQueryClipBox 

• GpiQueryClipRegion 

• GpiSetClipRegion 

• WinExcludellpdateRegion 

Example Code 

This example uses GpiExcludeClipRectangle to exclude a 100x100 rectangle, anchored at (100,100), 
from the clipping region. 

fdefine INCL_GPIREGIONS /* Region functions */ 

linclude <os2.h> 

LONG 1 Complexity; /* clipping complexity /error return */ 

HPS hps; /* Presentation-space handle */ 

RECTL prclRectangle = {100, 100, 200, 200};/* exclude rectangle */ 

1 Complexity = GpiExcludeClipRectangle (hps, Sprcl Rectangle) ; 
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GpiFillPath 
Fill Path 


#define INCL_GPIPATHS /* Or use INCL_GPI or INCL_PM */ 


LONG GpiFillPath (HPS hps, LONG IPath, LONG lOptlons) 


This function draws the interior of a path using the area attributes. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

IPath (LONG) - input 

Identifier of path whose interior is to be drawn; it must be 1. 

lOptlons (LONG) - input 
Fill option: 

FPATH_ALTERNATE Fills the path using the alternate rule; see GpiBeginArea. 

FPATH_WINDING Fills the path using the winding rule; see GpiBeginArea. This value must 
be selected if the path has been modified using GpiModifyPath. 

The default is FPATH_ALTERNATE. 

Returns 

Error indicator: 

GPI_OK Successful 

GPI_HITS Correlate hits 

GPI_ERROR Error. 

Possible returns from WinGetLastError 

PMERRJNVHPS 
PMERRPSBUSY 

PMERR_INV_PATH_ID 
PMERR_INV_FILL_PATH_OPTIONS 

PMERRPATHUNKNOWN 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid path identifier parameter was specified. 

An invalid options parameter was specified with 
GpiFillPath. 

An attempt was made to perform a path function on a path 
that did not exist. 


Remarks 

Any open figures within the path are closed. 

The path is deleted when the interior has been drawn. 

The boundaries of the area, as defined by the path, are considered to be part of the interior and are 
included in the fill. 

If the current drawing mode (see GpiSetDrawingMode) is draw or draw-and-retain, the interior is 
drawn on the currently associated device. If the drawing mode is retain, this function is stored in the 
current segment, and output occurs when the segment is subsequently drawn in the usual way. 
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GpiFillPath - 
Fill Path 


Related Functions 

Prerequisite Functions 

• GpiBeginPath 

Other Related Functions 

• GpiEndPath 

• GpiModifyPath 

• GpiOutlinePath 

• GpiPathToRegion 

• GpiPop 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiSetBackColor 

• GpiSetBackMix 

• GpiSetColor 

• GpiSetClipPath 

• GpiStrokePath 

• GpiSetLineEnd 

• GpiSetLineJoin 

• GpiSetLineType 

• GpiSetLineWidth 

• GpiSetLineWidthGeom 

• GpiSetPattern 

• GpiSetPatternRefPoint 

• GpiSetPatternSet 

• GpiSetMix 

Graphic Elements and Orders 

Element Type: OCODE_GFPTH 

Note that GpiStrokePath also generates this element type. 

Order: Fill Path 

Example Code 

This example uses the GpiFillPath function to draw the interior of the given path. The path, an 
isosceles triangle, is not closed when it is created, so the GpiFillPath function closes it before filling. 

Idefine INCL_GPIPATHS /* GPI Path functions */ 

linclude <os2.h> 

HPS hps; /* presentation space handle */ 

POINTL ptl Start = { 0, 0 }; /* first vertex */ 

POINTL ptlTri angle [] = { 100, 100, 200, 0, 0, 0 }; /* vertices */ 

GpiBeginPath (hps, 1L) ; /* create a path */ 

GpiMove(hps, &ptl Start); 

GpiPolyLine(hps, 3L, ptlTriangle) ; 

Gpi EndPath(hps) ; 

Gpi FillPath(hps, 1L, FPATH_ALTERNATE) ; /* fill the path */ 
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GpiFloodFill 
Flood Fill 


#define INCL_GPIBITMAPS /* Or use INCL_GPI or INCL_PM */ 


LONG GpiFloodFill (HPS hps, LONG lOptlons, LONG IColor) 


This function fills an area bounded by a given color, or while on a given color. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

lOptlons (LONG) - input 
Flood fill options: 

FF_BOUNDARY Fills up to the specified color 

FF_SURFACE Fills while on the specified color. 

IColor (LONG) - input 
Color. 

The boundary or surface color, depending on the value of / Options . 

This is either a logical color index, or an RGB value, depending on the state of the color table. 


Returns 

Correlation and error indicators: 
GPI_OK Successful 

GPI_HITS Correlate hits 

GPI_ERROR Error. 


Possible returns from WinGetLastError 


PMERRINVHPS 

PMERR_PS_BUSY 

PMERRFUNCTIONNOTSUPPORTED 

PMERR_INV_FLOOD_FILL_OPTIONS 

PMERRINVINAREA 


PMERR_INV_IN_PATH 
PM E R R_IN V_COLOR_ATTR 

PMERRINSUFFICIENTMEMORY 

PMERR_START_POINT_CLIPPED 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

The function is not supported. 

Invalid flood fill parameters were specified. 

An attempt was made to issue a function invalid inside an 
area bracket. This can be detected while the actual 
drawing mode is draw or draw-and-retain or during 
segment drawing or correlation functions. 

An attempt was made to issue a function invalid inside a 
path bracket. 

An invalid color attribute value was specified or the 
default value was explicitly specified with GpiSetAttrs 
instead of using the defaults mask. 

The operation terminated through insufficient memory. 

The starting point specified for flood fill is outside the 
current clipping path or region. 
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GpiFloodFill - 
Flood Fill 


PMERR_NO_FILL No flood fill occured because either the starting point 

color was the same as the input color when a boundary 
fill was requested, or the starting point color was not the 
same as the input color when a surface fill was 
requested. 


Remarks 

The seed point is current position, which is unchanged by this function. 

The area attributes define the fill. 

DevQueryCaps (CAPS_RASTER_FLOOD_FILL) indicates whether GpiFloodFill is supported on any 
particular device. 

The results produced by this function are highly device-dependent. 

When the drawing mode is draw, if 

If the presentation space is partially obscured by an overlying window an incorrect fill can result. 

When filling over a pattern or a dithered color, the individual color of each pel is taken into account. 

Note: This function must not be used when creating SAA-conforming metafiles; see “Metafile 
Restrictions” on page G-1. 

Related Functions 

Prerequisite Functions 

• GpiBeginArea 

• GpiBeginPath 

• GpiFillPath 

• GpiSetPel 

Example Code 

This function uses GpiFloodFill to fill an area bounded by a given color, or while on a given color. 
The example assumes the color table is in index mode; it fills up to the boundary where the color 
represented by index 1 appears. 


Idefine INCL_GPIBITMAPS /* Bit map functions */ 

linclude <os2.h> 


LONG 

lHits; 

/* correlation/error indicator 

*/ 

HPS 

bps; 

/* Presentation-space handle 

*/ 

LONG 

lOptions; 

/* flood fill options 

*/ 

LONG 

IColor; 

/* color 

*/ 


/* fill up to the boundaries of the color */ 
1 Options = FF_BOUNDARY ; 

/* use color corresponding to index 1 */ 

1 Col or = 1; 

lHits = GpiFloodFill (hps, lOptions, IColor); 
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GpiFrameRegion 
Frame Region 


#define INCL_GPIREGIONS /* Or use INCL_GPI or INCL_PM */ 


LONG GpiFrameRegion (HPS hps, HRGN hrgn, PSIZEL psIziThlckness) 


This function draws a frame inside a region using the current pattern attributes. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

hrgn (HRGN) - input 
Region handle. 

psIziThlckness (PSIZEL) - input 
Thickness of frame. 

The width and height of the rectangle, in device coordinates, used to trace the frame. Both the 
width and height fields must be greater than or equal to zero. 


Returns 

Correlation and error indicators: 

GPI_OK Successful 

GPI_HITS Correlate hits 

GPI_ERROR Error. 

Possible returns from WinGetLastError 

PMERRINV HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_REGION_IS_CLIP_REGION An attempt was made to perform a region operation on a 

region that is selected as a clip region. 

PMERR_INV_HRGN An invalid region handle was specified. 

PMERR_HRGN_BUSY An internal region busy error was detected. The region 

was locked by one thread during an attempt to access it 
from another thread. 

Remarks 

The frame is drawn by tracing around the inner boundary of the region with a rectangle of size given 
by the psizIThickness parameter. The edge of the frame includes the pels on the left and bottom 
boundaries of the region, unless those pels are also on the top and right boundaries, in which case 
they are excluded. 

No part of the frame is drawn outside the region. 

The region is assumed to be defined in device coordinates. 

It is invalid if the specified region is currently selected as the clip region (by GpiSetClipRegion). 

Note: This function must not be used when creating SAA-conforming metafiles; see "Metafile 
Restrictions” on page G-1. 


5-146 PM Programming Reference 







GpiFrameRegion - 
Frame Region 


Example Code 

This example uses GpiFrameRegion to draw a frame of width 5 around an existing region. 


Idefine INCL_GPIREGIONS /* Region functions */ 

linclude <os2.h> 

LONG lHits; /* correlation/error indicator */ 

HPS hps; /* presentation-space handle */ 

HRGN hrgn; /* handle for region */ 

SIZEL psizlThickness = {5L.5L}; 

/* Thickness of frame */ 


RECTL arcl [3] = { 100, 100, 200, 200, /* 1st rectangle */ 

150, 150, 250, 250, /* 2nd rectangle */ 

200, 200, 300, 300 }; /* 3rd rectangle */ 

/* create a region comprising three rectangles */ 
hrgn = GpiCreateRegion(hps, 3L, arcl); 

lHits = GpiFrameRegion (hps, hrgn, &psizlThickness) ; 
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GpiFullArc 
Full Arc 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM 7 


LONG GpIFuiiArc (HPS hps, LONG 'Control, FIXED fxMultlpller) 


This function creates a full arc with its center at the current position. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

IControl (LONG) - input 

Interior and outline control. 

Specifies whether the interior of the full arc should be filled, and whether the outline should be 
drawn: 

DRO_FILL Fill interior 

DRO_OUTLINE Draw outline 

DRO_OUTLINEFILL Draw outline and fill interior. 

fxMultlpller (FIXED) - input 
Multiplier. 

This determines the size of the arc, in relation to an arc with the current arc parameters. The 
implementation limit of the multiplier is 255. 

The value must not be negative. 


Returns 

Correlation and error indicators: 

GPI_OK Successful 

GPI_HITS Correlate hits 

GPI_ERROR Error. 

An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid control parameter was specified with 
GpiFullArc. 

An invalid multiplier parameter was specified with 
GpiPartialArc or GpiFullArc. 


Possible returns from WinGetLastError 

PMERRINVHPS 

PMERRPSBUSY 

PMERR INV_ARC_CONTROL 

PMERRJNVMULTIPLIER 


Remarks 

The current position is not changed. 

The arc parameters determine whether the full arc is drawn clockwise or counterclockwise. 
Either the outline of the full arc, or its interior, or both, can be drawn. 

If this function appears within an area or path definition, it generates a complete closed figure 
(DRO_OUTLINE must be specified). It must not occur within any other figure definition. 
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GpiFullArc - 
Full Arc 


If correlation is in force, a hit always results if the pick aperture intersects the full arc boundary. 
However, if the pick aperture lies wholly within the figure, a hit only occurs if the interior is being 
drawn (DRO_FILL or DRO_OUTLINEFILL). 

Related Functions 

• GpiPartialArc 

• GpiPointArc 

• GpiSetCurrentPosition 

• GpiSetArcParams 

• GpiSetDefArcParams 

• GpiSetLineType 

• GpiSetLineWidth 

• GpiPop 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiSetBackColor 

• GpiSetBackMix 

• GpiSetColor 

• GpiSetMix 

Graphic Elements and Orders 

Element Type: OCODE_GCFARC 
Order: Begin Area 

This order is generated only if I Control is DRO_FILL or DRO_OUTLINEFILL. 

Order: Full Arc at Current Position 
Order: End Area 

This order is generated only if / Control is DRO_FILL or DRO_OUTLINEFILL. 

Example Code 

This example uses GpiFullArc to draw five concentric circles. The arc parameters are set before 
drawing the arc. Only the outline is drawn for the arc. 


Idefine INCL_GPIPRIMITIVES /* GPI primitive functions */ 
finclude <os2.h> 

HPS hps; /* presentation space handle */ 
SHORT i; /* loop variable */ 
ARCPARAMS arcp = { 1, 1, 0, 0 }; /* arc parameters structure */ 


GpiSetArcParams (hps, Sarcp); 

for (i = 5; i > 0; i--) 

Gpi Full Arc (hps, 
DR0_0UTLINE, 
MAKEFIXED ( i , 0)); 


/* presentation-space handle */ 
/* outline */ 
/* converts integer to fixed point */ 
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GpiGetData 
Get Data 


#define INCL_GPISEGMENTS /* Or use INCL_GPI or INCL_PM */ 


LONG GpiGetData (HPS hps, LONG ISegld, PLONG plOffset, LONG IFormat, LONG ILength, 
PBYTE pbData) 


This function retrieves a buffer of graphic data from the specified segment into the supplied buffer. 
The data is a list of drawing orders. For details of these, see Chapter 33, “Graphics Orders.” 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

ISegld (LONG) - input 
Segment identifier. 

plOffset (PLONG) - input/output 
Segment offset. 

A value used to indicate the position in the segment from which data is to be retrieved. It must 
be set to 0 the first time GpiGetData is called. This indicates that data is to be obtained from the 
start of the segment. On return, it contains a value that can be used on a subsequent call to 
continue data retrieval. 

The only possible values that can be specified are 0 or the value returned from a previous 
function. 

IFormat (LONG) - input 

Coordinate type required: 

DFORM_NOCONV No coordinate conversion performed. 

ILength (LONG) - input 
Length of data buffer. 

pbData (PBYTE) - output 
Data buffer. 

For order formats, see Chapter 33, “Graphics Orders” on page 33-1. 


Returns 

Length of returned data. 

>0 Number of bytes actually returned in pbData 

GPI.ALTERROR Error. 


Possible returns from WinGetLastError 

PMERRINVHPS 

PMERRPSBUSY 

PMERRINVSEGNAME 
P M E R R_IN V_SEG_OFFSET 

PMERRJNVGETDATACONTROL 

PMERR_INV_LENGTH_OR_COUNT 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid segment identifier was specified. 

An invalid offset parameter was specified with 
GpiPutData. 

An invalid format parameter was specified with 
GpiGetData. 

An invalid length or count parameter was specified. 
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GpiGetData - 
Get Data 


PMERR_INV_MICROPS_FUNCTION 

PMERRSEGNOTFOUND 

PMERRSEGISCURRENT 

PMERR_DATA_TOO_LONG 


An attempt was made to issue a function that is invalid in 
a micro presentation space. 

The specified segment identifier did not exist 

An attempt was made to issue GpiGetData to a segment 
that was currently open. 

An attempt was made to transfer more than the maximum 
permitted amount of data (64512 bytes) using GpiPutData, 
GpiGetData, or GpiElement. 


Remarks 

If the buffer is large enough to contain the data requested, the data is returned and / Count is set to 
show its length. 

If the buffer is not large enough, the buffer is filled and / Count is set to the length of the buffer. This 
may mean that there is an incomplete order at the end of the buffer; even so, it is possible to use 
GpiPutData subsequently, without having to scan the orders in the buffer. 

The application can detect when it has been given all the data by checking the ICount value. If this is 
less than the value of / Length specified, there is no more data to be returned. If it is equal, there is 
more data, except in the case where the data just fits in the buffer, which is detected if another 
GpiGetData function is issued, and a ICount of 0 is returned. 

No conversion of coordinates is performed for the DFORM NOCONV value of the control parameter. 
The coordinates are in the presentation space format. 

This function can be issued while there is a segment open, unless the open segment is the segment 
referenced by this function. If the segment referenced by this function is open, an error occurs. 

The segment transform and viewing transform are not returned by this call. 


Related Functions 

• GpiPutData 
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GpiGetData 
Get Data 


Example Code 

This example uses the GpiGetData function to copy data from one segment to another. 


Idefine INCL_GPISEGMENTS /* Segment functions */ 

linclude <os2.h> 


HPS hps; 

LONG f Format = DF0RM_N0C0NV; 
LONG off Segment = 0L; 

LONG offNextElement = 0L; 
LONG cb = OL; 


BYTE abBuffer[512] ; /* data buffer 


/* presentation space handle */ 
does not convert coordinates */ 

/* offset in segment */ 

/* offset in segment to next element */ 
/* bytes retrieved */ 


7 


GpiOpenSegment(hps, 3L); /* opens segment to receive data */ 

do { 

off Segment += cb; 

offNextElement = off Segment; 

cb = GpiGetData(hps, 2L, &offNextElement, fFormat, 512L, 
abBuffer) ; 

/* Put data in other segment. */ 

if (cb > 0L) GpiPutData(hps, /* presentation-space handle */ 

fFormat, /* format of coordinates */ 

&cb, /* number of bytes in buffer */ 

abBuffer); /* buffer with graphics-order data */ 

} while (cb > 0); 

GpiCloseSegment(hps) ; /* closes segment that received data */ 
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Gpilmage - 
Image 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


LONG Gpilmage (HPS hps, LONG IFormat, PSIZEL psIzIlmageSIze, LONG ILength, 
PBYTE pbData) 


This function draws a rectangular image, with the top-left corner at the current position. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

IFormat (LONG) - input 
Format of image data. 

This is a reserved field; must be set to 0. 

psizIlmageSize (PSIZEL) - input 
Size of image area (in pels). 

The maximum width allowed is 2 040. 

ILength (LONG) - input 

Length in bytes of image data. 

pbData (PBYTE) - input 
Image data. 


Returns 

Correlation and error indicators: 
GPI_OK Successful 

GPI_HITS Correlate hits 

GPI_ERROR Error. 


Possible returns from WinGetLastError 


PMERRINVHPS 

PMERR_PS_BUSY 

PMERRINVIMAGEFORMAT 

PMERR _INV _IMAGE_DAT ALENGTH 

PMERRJNVIMAGEDIMENSION 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid IFormat parameter was specified with 
Gpilmage. 

An invalid ILength parameter was specified with 
Gpilmage. There is a mismatch between the image size 
and the data length. 

An invalid psizIlmageSize parameter was specified with 
Gpilmage. 


Remarks 

All images are a rectangular array of pels (display points), each pel being represented by one bit. 

psizIlmageSize, which defines the width and height of the image, determines how many pels there 
are in the horizontal and vertical directions. 
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Gpilmage 

Image 


pbData determines which of the pels are visible; a 1 bit sets the associated pel, using the image 
foreground color and mix, and a 0 bit sets the pel using the image background color and mix. 

The top left-hand corner of the image is placed at the current position, and the data supplied is drawn 
row by row, starting at the top. Each row is drawn from left to right and must be padded out to an 
integral number of bytes if the image width specified is not a multiple of 8. For example, if the image 
width specified is 12, each row of data must be padded out to a length of 16 so that the data in the 
row occupies exactly 2 bytes. 

Within each byte the high-order bit is drawn on the left. 

The length of image data specified must include the padding of each row of data. The length must be 
given in bytes, and an error message is issued if it is wrong. 

If the image is being stored in a metafile, then (((pels_per_row + 9) / 8) * pels_per_column) + 10, 
must be less than 32768. 

Because of the different sizes of pels for different devices, the relationship of the image with respect 
to other graphics primitives is device-dependent. 

The current position remains unchanged after the image has been drawn. 


Related Functions 

• GpiSetAttrs 

• GpiSetBackColor 

• GpiSetBackMix 

• GpiSetColor 

• GpiSetMix 

Graphic Elements and Orders 

Element Type: OCODE_GCBIMG 
Order: Begin Image at Current Position 
Order: Image Data 

One order for each pel row of the image. 

Order: End Image 

Example Code 

This example uses Gpilmage to draw an 8-by-8 image. The image data is specified as an array of 
bytes. 

Idefine INCL_GPI PRIMITIVES /* GPI primitive functions */ 
linclude <os2.h> 

HPS hps; /* presentation space handle */ 

SIZEL sizl = { 8, 8 }; /* image is 8 pels wide by 8 pels high */ 

BYTE ablmage[] = { 0x00, 0x18, 0x3c, 0x7e, 0xff, 

0xff, 0x7e, 0x3c, 0x18, 0x00 }; /* image data */ 

Gpilmage(hps, 0L, &sizl, 8L, ablmage); /* draws the image */ 
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GpilntersectClipRectangle - 
Intersect Clip Rectangle 


#define INCL_GPIREGIONS /* Or use INCL_GPI or INCL_PM */ 


LONG GpilntersectClipRectangle (HPS hps, PRECTL prcIRectangle) 


This function sets the new clip region to the intersection of the current clip region and the specified 
rectangle. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

prcIRectangle (PRECTL) - input 

prcIRectangle, the coordinates of which are world coordinates. 


Returns 

Complexity of clipping and error indicators. 

The clipping complexity information includes the combined effects of: 

• Clip path 

• Viewing limits 

• Graphics field 

• Clip region 

• Visible region (windowing considerations). 

RGN_NULL Null region 

RGN_RECT Rectangular region 

RGN_COMPLEX Complex region 
RGN_ERROR Error. 

Possible returns from WinGetLastError 

PMERR_INV_HPS 
PMERR_PS_BUSY 

PMERRINVCOORDINATE 
PMERRJNVRECT 

Remarks 

The boundaries of the rectangle are considered to be part of the interior, so that a point on the 
rectangle boundary is not clipped (removed) if it was previously within the clip region. 

This function creates a clip region if one does not currently exist. The application is responsible for 
freeing this (with GpiDestroyRegion), if it subsequently selects another clip region (see 
GpiSetClipRegion). Any clip region still selected when the device context is closed is automatically 
freed. 

Note: This function must not be used when creating SAA-conforming metafiles; see “Metafile 
Restrictions” on page G-1 . 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid coordinate value was specified. 

An invalid rectangle parameter was specified. 
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GpilntersectClipRectangle 
Intersect Clip Rectangle 


Related Functions 

• GpiExcludeClipRectangle 

• GpiOffsetClipRegion 

• GpiQueryClipBox 

• GpiQueryClipRegion 

• GpiSetClipRegion 

Example Code 

This example uses GpilntersectClipRectangle to create a new clipping region, consisting of the 
intersection of the old clipping region and a 100x100 rectangle, anchored at (100,100). 

Idefine INCL_GPIREGIONS /* Region functions */ 

linclude <os2.h> 

LONG 1 Complexity; /* clipping complexity/error return */ 

HPS hps; /* Presentation-space handle */ 

RECTL prcl Rectangle = {100,100,200,200}; /* intersect rectangle */ 

Complexity = GpiIntersectClipRectangle(hps, &prcl Rectangle); 
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GpiLabel - 
Label 


#define INCL_GPISEGEDITING /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiLabel (HPS bps, LONG ILabel) 


This function generates an element containing the specified label. 

Parameters 

bps (HPS) - input 

Presentation-space handle. 

ILabel (LONG) - input 
Required label. 

No check is made on the value of this parameter. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An attempt was made to issue a function that is invalid in 
a micro presentation space. 

An attempt was made to issue a function invalid inside an 
element bracket. 


Possible returns from WinGetLastError 

PMERRINVHPS 

PMERRPSBUSY 

PMERR_INV_MICROPS_FUNCTION 

PMERRINVINELEMENT 


Remarks 

This function has no effect unless a retained segment is being constructed. It is invalid within an 
element bracket. Duplicate labels within a segment are allowed. 


Related Functions 

• GpiSetElementPointerAtLabel 

• GpiSetTag 


Graphic Elements and Orders 

Element Type: OCODE_GLABL 
Order: Label 
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GpiLabel - 
Label 

Example Code 

This example uses the GpiLabel function to create label elements in a segment. If the segment is 
subsequently edited, the label elements can still be used to locate the elements near it. 

Idefine INCL_GPISEGEDITING /* GPI Segment Edit functions */ 
linclude <os2.h> 

HPS hps; /* presentation space handle */ 

POINTL ptlStart = { 0, 0 }; /* first vertex */ 

POINTL ptlTriangle[] = { 100, 100, 200, 0, 0, 0 }; /* vertices */ 

GpiOpenSegment(hps, 4L); /* creates a segment */ 

GpiLabel (hps, 5L); /* creates label 5 */ 

GpiLabel (hps, 10L); /* creates label 10 */ 

GpiMove(hps, &ptl Start); 

GpiCloseSegment(hps) ; 

GpiPolyLine(hps, 3L, ptlTriangle) ; 
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GpiLine - 
Line 


^define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM. Also in COMMON section */ 

LONG GpiLine (HPS hps, PPOINTL pptiEndPoInt) 

This function draws a straight line from the current position to the specified end point. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

pptiEndPoInt (PPOINTL) - input 
End point of the line. 

Returns 

Correlation and error indicators: 

GPI_OK Successful 

GPI_HITS Correlate hits 

GPI_ERROR Error. 

Possible returns from WinGetLastError 

PMERRINVHPS 
PMERRPSBUSY 

PMERRINVCOORDINATE 
PMERRINVNESTEDFIGURES 

Remarks 

The current position is set to the end point of the line. 

The line is drawn using the current values of the line color, line mix, line width, and line type 
attributes. 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid coordinate value was specified. 

Nested figures have been detected within a path 
definition. 
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GpiLine 

Line 


Related Functions 

• GpiBox 

• GpiMove 

• GpiPolyLine 

• GpiQueryCurrentPosition 

• GpiSetCurrentPosition 

• GpiSetLineEnd 

• GpiSetLineJoin 

• GpiSetLineType 

• GpiSetLineWidth 

• GpiSetLineWidthGeom 

• GpiPop 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiSetBackColor 

• GpiSetBackMix 

• GpiSetColor 

• GpiSetMix 

Graphic Elements and Orders 

Element Type: OCODEGCLINE 

Note that GpiPolyLine also generates this element type. 

Order: Line at Current Position 


Example Code 

This example uses GpiLine to draw an X. 

Idefine INCL_GPI PRIMITIVES /* GPI primitive functions */ 

linclude <os2.h> 

HPS hps; /* presentation space handle */ 

/* point array */ 

POINTL ptl [4] = { 0, 0, 100, 100, 0, 100, 100, 0 }; 

GpiMove(hps, &ptl [0] ) ; 

GpiLine(hps, &ptl [1]); 

GpiMove (hps, &ptl [2] ) ; 

GpiLine(hps, &ptl[3]); 
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GpiLoadBitmap - 
Load Bit Map 


#define INCL_GPIBITMAPS /* Or use INCL_GPI or INCL_PM. Also in COMMON section */ 


H BITMAP GpiLoadBitmap (HPS hps, HMODULE Resource, ULONG IdBItmap, LONG IWIdth, 

LONG IHelght) 


This function creates and loads a bit map from a resource, and returns the bit-map handle. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

The associated device should, if possible, hold the bit map in its own memory. Where this is not 
possible, main memory is used and the bit map is held in a format compatible with the device. 

Resource (HMODULE) - input 

Resource identity containing the bit map: 

NULLHANDLE Use the .EXE file of the application. 

Other Module handle returned from the OS/2 DosLoadModule function. 

IdBItmap (ULONG) - input 

ID of the bit map within the resource file. 

IWIdth (LONG) - input 

Width of the bit map in pels. 

IHelght (LONG) - input 

Height of the bit map in pels. 


Returns 

Bit-map handle: 

^0 Bit-map handle 

GPI_ERROR Error. 


Possible returns from WinGetLastError 


PMERRINVHPS 

PMERR_PS_BUSY 

PMERRBITMAPNOTFOUND 

PMERRINVBITMAPDIMENSION 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

A attempt was made to perform a bit-map operation on a 
bit map that did not exist. 

An invalid dimension was specified with a load bit-map 
function. 


Remarks 

Some bit-map functions, including drawing into the bit map, require it to be selected into a memory 
device context, using GpiSetBitmap. This is true whether device or main memory is used to hold the 
bit map. 

The bit map is stretched to the specified /Width and /Height. If /Width or /Height is 0, the bit map is 
not stretched in that direction; when, for example, /Width = 0, the bit map is not stretched 
horizontally, when /Height = 0, it is not stretched vertically. 

The bit map may have been created by the icon editor in bit-map mode. 
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GpiLoadBitmap 
Load Bit Map 


There are a number of standard bit-map formats that should normally be adhered to. Other formats 
can be used if supported by the device. 

The bit map is owned by the process from which this function is issued. It cannot be accessed 
directly from any other process. If it still exists when the process terminates, it is automatically 
deleted by the system. 


Related Functions 

• GpiBitBIt 

• GpiCreateBitmap 

• GpiDeleteBitmap 

• GpiDrawBits 

• GpiQueryBitmapBits 

• GpiQueryBitmapDimension 

• GpiQueryBjtmapHandle 

• GpiQueryBitmapParameters 

• GpiQueryDeviceBitmapFormats 

• GpiSetBitmap 

• GpiSetBitmapBits 

• GpiSetBitmapDimension 

• GpiSetBitmapId 

• GpiWCBitBIt 

• WinDrawBitmap 

• WinGetSysBitmap 

Example Code 

This example uses the GpiLoadBitmap function to load a bit map from the .EXE file into application 
memory. The bit map is then selected, displayed, and finally, deleted from memory. 

Idefine INCL_GPIBITMAPS /* GPI bit map functions */ 

linclude <os2.h> 

HPS hps; /* presentation space handle */ 

HBITMAP hbm, hbmPrevious; 

Idefine BITMAP_ID 1 

/* load the bit map from the EXE */ 

hbm = GpiLoadBitmap (hps, NULLHANDLE, BITMAP_ID, 10OL, 100L); 
hbmPrevious = GpiSetBitmap (hps, hbm); /* select bit map for PS */ 

/* bit map displayed with GpiBitBIt */ 

GpiSetBitmap (hps, hbmPrevious); /* release bit map from PS */ 

GpiDeleteBitmap(hbm) ; /* delete the bit map */ 
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GpiLoadFonts - 
Load Fonts 


#define INCL_GPILCIDS /* Or use INCL_GPI or INCL_PM 7 


BOOL GpiLoadFonts (HAB hab, PSZ pszFllename) 


This function loads one or more fonts from the specified resource file. 

Parameters 

hab (HAB) - input 

Anchor-block handle. 

pszFllename (PSZ) - input 
Filename. 

This is the fully-qualified name of the font resource. The file-name extension is ".FON.” 

Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERR_INV_FONT_FILE_DATA The font file specified with GpiLoadFonts, 

GpiLoadPublicFonts, 


Remarks 

All of the fonts in the file become available for any presentation space (GPI or VIO) created by the 

same process. They are not available for any other process. 

The format of the font definitions in the resource file is defined in Appendix F, “The Font-File 

Format” on page F-1. 

When no longer required, the fonts may be unloaded with GpiUnloadFonts. 

Note: Fonts loaded with GpiLoadFonts are not available for use for spooled printing, that is if a 
device type of OD_QUEUED is specified in DevOpenDC; in this case GpiCreateLogFont will 
never return FONT_MATCH for these fonts. To avoid this, install the fonts as public fonts 
using the Font Palette object located in the System Setup folder, on both the generating and 
the receiving workstations if these are different. 


Related Functions 

• GpiCreateLogFont 

• GpiDeleteSetld 

• GpiQueryFontMetrics 

• GpiQueryFonts 

• GpiQueryKerningPairs 

• GpiQueryNumberSetlds 

• GpiQuerySetlds 

• GpiQueryWidthTable 

• GpiUnloadFonts 

• GpiSetCharSet 
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GpiLoadFonts - 
Load Fonts 

Example Code 

This example uses the GpiLoadFonts function to load all fonts from the font resource file HELV.FON. 
The GpiQueryFonts function retrieves the number of fonts loaded. 


Idefine INCL_GPI LCIDS /* Font functions */ 
linclude <os2.h> 

HPS hps; /* presentation space handle */ 
HAB hab; /* anchor-block handle */ 
LONG cFonts = 0L; /* font count */ 
LONG remFonts; /* fonts not returned */ 


GpiLoadFonts(hab, "helv"); 

remFonts = GpiQueryFonts(hps, QF_PRIVATE, NULL, &cFonts, OL, NULL); 
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GpiLoadMetaFile - 
Load Metafile 


#define INCL_GPIMETAFILES /* Or use INCL_GPI or INCL_PM */ 


HMF GpiLoadMetaFile (HAB hab, PSZ pszFllename) 


This function loads data from a file into a metafile. 

Parameters 

hab (HAB) - input 

Anchor-block handle. 

pszFllename (PSZ) - input 
Filename. 

The name of the file that is to be loaded into a metafile. 

Returns 

Metafile handle or error: 

Metafile handle 
GPI.ERROR Error. 

Possible returns from WinGetLastError 

PMERRDOSOPENFAILURE 

PMERRDOSREADFAILURE 


A DosOpen call made during GpiLoadMetaFile or 
GpiSaveMetaFile gave a good return code but the file was 
not opened successfully. 

A DosRead call made during GpiLoadMetaFile gave a 
good return code. However, it failed to read any more 
bytes although the file length indicated that there were 
more to be read. 


Remarks 

A metafile is created, into which the data from the file is loaded. The handle of the metafile created 
is returned in hmf\ it can be used on subsequent GpiPlayMetaFile or GpiDeleteMetaFile functions. 

Related Functions 

• GpiCopyMetaFile 

• GpiDeleteMetaFile 

• GpiPlayMetaFile 

• GpiQueryMetaFileBits 

• GpiQueryMetaFileLength 

• GpiSaveMetaFile 

• GpiSetMetaFileBits 
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GpiLoadMetaFile - 
Load Metafile 

Example Code 

This example uses the GpiLoadMetaFile function to load a metafile with data from the file 
sample.met. Later, the metafile is deleted by using the GpiDeleteMetaFile function. 

Idefine INCL_GPIMETAFILES /* Metafile functions */ 

linclude <os2.h> 

HAB hab; /* anchor block handle */ 

HMF hmf; /* metafile handle */ 

/* loads metafile from disk */ 

hmf = GpiLoadMetaFile (hab, "sample.met"); 


GpiDeleteMetaFile(hmf) ; /* deletes metafile */ 
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GpiLoadPublicFonts - 
Load Public Fonts 


#define INCL_GPILCIDS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiLoadPublicFonts (HAB hab, PSZ pszFllename) 


This function loads one or more fonts from the specified resource file, to be available for all 
applications. 

Parameters 

hab (HAB) - input 

Anchor-block handle. 

pszFllename (PSZ) - input 
Filename. 

This is the fully-qualified name of the font resource. The file-name extension is “.FON.” 

Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRINSUFFICIENTMEMORY 
PMERR_INV_FONT_FILE_DATA 


The operation terminated through insufficient memory. 

The font file specified with GpiLoadFonts, 
GpiLoadPublicFonts, 


Remarks 

All of the fonts in the file become available for any presentation space (GPI or VIO) created by any 
process. 

The format of the font definitions in the resource file is defined in Appendix F, “The Font-File 
Format” on page F-1 . 

Note: Problems can occur when applications load and unload public fonts. See 
GpillnloadPublicFonts. 

Example Code 

This example use GpiLoadPublicFonts to load and make available fonts from a file 'TEST.FON', 
which is assumed to exist and contain valid fonts. 


Idefine INCL_GPILCIDS /* Font functions */ 

linclude <os2.h> 


BOOL 

fSuccess; 

/* 

success indicator 

*/ 

HAB 

hab; 

/* 

anchor-block handle 

*/ 

char 

pszFi lename[13] ; 

/* 

Name of fond resource file 

*/ 


/* resource file is named 'TEST.FON' */ 
strcpy(pszFi lename, "TEST. FON" ) ; 

fSuccess = GpiLoadPublicFonts (hab, pszFi lename); 
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GpiMarker 

Marker 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM 7 


LONG GpiMarker (HPS hps, PPOINTL pptiPoInt) 


This function draws a marker with its center at a specified position. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

pptiPoInt (PPOINTL) - input 
Position of the marker. 


Returns 

Correlation and error indicators: 

GPI_OK Successful 

GPI_HITS Correlate hits 

GPI_ERROR Error. 

Possible returns from WinGetLastError 

PMERR_INV_HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_COORDINATE An invalid coordinate value was specified. 

Remarks 

The current position is moved to the specified position. The marker symbol is selected by the 
current values of the marker set and marker symbol attributes. 


Related Functions 

• GpiPolyMarker 

• GpiSetMarker 

• GpiSetMarkerBox 

• GpiSetMarkerSet 

• GpiSetLineEnd 

• GpiSetLineJoin 

• GpiSetLineType 

• GpiSetLineWidth 

• GpiSetLineWidthGeom 

• GpiPop 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiSetBackColor 

• GpiSetBackMix 

• GpiSetColor 

• GpiSetMix 
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GpiMarker - 
Marker 


Graphic Elements and Orders 

Element Type: OCODE_GMRK 

Note that GpiPolyMarker also generates this element type. 
Order: Marker at Given Position 


Example Code 

This example uses the GpiMarker function to draw a marker at the point (10,10). 

Idefine INCL_GPIPRIMITIVES /* GPI primitive functions */ 
linclude <os2.h> 

HPS hps; /* presentation space handle */ 

POINTL ptl = { 10, 10 }; /* marker point */ 

GpiMarker (hps, &ptl ) ; 
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GpiModifyPath 
Modify Path 


#define INCL_GPIPATHS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiModifyPath (HPS hps, LONG IPath, LONG IMode) 


This function modifies the specified path. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

IPath (LONG) - input 
Path identifier. 

Identifier of the path to be modified; it must be 1. 

IMode (LONG) - input 
Modification required. 

This must be: 

MPATH_STROKE Convert the path to one describing the envelope of a wide line. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 


PMERRINVHPS 

PMERR_PS_BUSY 

PM E R R_IN V_P ATHJD 
PMERR_INV_MODIFY_PATH_MODE 

PMERRPATHUNKNOWN 

PM ERRCOORDIN ATEOVERFLOW 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid path identifier parameter was specified. 

An invalid mode parameter was specified with 
GpiModifyPath. 

An attempt was made to perform a path function on a path 
that did not exist. 

An internal coordinate overflow error occurred. This can 
occur if coordinates or matrix transformation elements (or 
both) are invalid or too large. 


Remarks 

This function converts the path to one describing the envelope of a wide line stroked using the 
current geometric wide-line attribute (see GpiSetLineWidthGeom). Note that this and GpiStrokePath 
are the only calls that can cause geometric wide lines to be constructed. 

The envelope includes the effects of line joins, and line ends, according to the current values of these 
attributes (see GpiSetLineJoin and GpiSetLineEnd). Note these points: 

• A line may be joined to an arc, for example. The common point is handled according to the 
line-join attribute, rather than applying line ends at each end. 

• Any open figures within the path are not closed automatically. 
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GpiModifyPath - 
Modify Path 


• If a figure is closed using GpiCloseFigure, the joining rules are followed, rather than the ending 
rules, at the start and end point. 

• The envelope takes account of any crossings, so that a character such as a stroked “X” does not 
have a hole in the middle when subsequently drawn in exclusive-OR mode. 

After this function, the only calls that can be performed on the path are GpiFillPath, specifying the 
FPATH_WINDING option, or GpiSetClipPath, specifying the SCP_WINDING option. 


Related Functions 

• GpiBeginPath 

• GpiEndPath 

• GpiFillPath 

• GpiOutlinePath 

• GpiPathToRegion 

• GpiSetClipPath 

• GpiSetPattern 

• GpiSetPatternRefPoint 

• GpiSetPatternSet 

• GpiStrokePath 

• GpiSetLineEnd 

• GpiSetLineJoin 

• GpiSetLineType 

• GpiSetLineWidth 

• GpiSetLineWidthGeom 

• GpiPop 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiSetBackColor 

• GpiSetBackMix 

• GpiSetColor 

• GpiSetMix 

Graphic Elements and Orders 

Element Type: OCODE_GMPTH 
Order: Modify Path 
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Modify Path 


Example Code 

This example uses the GpiModifyPath function to modify the given path. The GpiFillPath function 
then draws the path. 

Idefine INCL_GPIPATHS /* GPI Path functions */ 

linclude <os2.h> 

HPS hps; /* presentation space handle */ 

POINTL ptlStart = { 0, 0 }; /* first vertex */ 

POINTL ptlTrianglet] = { 100, 100, 200, 0, 0, 0 }; /* vertices */ 

GpiBeginPath(hps, 1L); /* creates path */ 

GpiMove(hps, &ptl Start) ; 

GpiPolyLine(hps, 3L, ptlTriangle) ; 

GpiEndPath(hps); 

GpiModifyPath(hps, 

1L, 

MPATHSTROKE) ; /* modifies path for wide line */ 

Gpi Fill Path (hps , 1L, FPATHALTERNATE) ; /* draws the wide line */ 
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GpiMove - 
Move 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM. Also in COMMON section */ 


BOOL GpiMove (HPS hps, PPOINTL pptIPoInt) 


This function moves the current position to the specified point. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

pptIPoInt (PPOINTL) - input 
Position to which to move. 

This position is in world coordinates. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRJNV HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_COORDINATE An invalid coordinate value was specified. 

Remarks 

This function also has the effect of resetting position within a line-type sequence, and, if within an 
area, of starting a new closed figure and causing any previous one to be closed automatically if 
necessary. 

This function is equivalent to the GpiSetCurrentPosition call, except that, if the current attribute mode 
is AMPRESERVE (see GpiSetAttrMode), the current position is not saved before being set to a new 
value by the GpiMove function, and hence cannot be restored using the GpiPop call. 


Related Functions 

• GpiQueryCurrentPosition 

• GpiSetCurrentPosition 

Graphic Elements and Orders 

Element Type: OCODE_GSCP 

Note that GpiSetCurrentPosition also generates this element type. 
Order: Set Current Position 
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GpiMove - 
Move 


Example Code 

This example uses the GpiMove function to draw an X. The function moves the current position to 
the starting point of each leg of the character. 

Idefine INCL_GPIPRIMITIVES /* GPI primitive functions */ 
linclude <os2.h> 

HPS hps; /* presentation space handle */ 

/* point array */ 

POINTL ptl [4] = { 0, 0, 100, 100, 0, 100, 100, 0 }; 

GpiMove(hps, &ptl [0] ) ; /* move to (0,0) */ 

GpiLine(hps, &ptl [1] ) ; 

GpiMove(hps, &ptl [2] ) ; /* move to (0,100) */ 

Gpi Line (hps, &ptl [3] ) ; 


5-174 PM Programming Reference 



GpiOffsetClipRegion - 
Offset Clip Region 


#define INCL_GPIREGIONS /* Or use INCL_GPI or INCL_PM 7 


LONG GpiOffsetClipRegion (HPS hps, PPOINTL pptiPoInt) 


This function moves the clipping region by the specified displacement. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

pptiPoInt (PPOINTL) - input 
Displacement. 

The displacement by which the clipping region is to be moved, expressed as an offset in world 
coordinates. 


Returns 

Complexity of clipping and error indicators. 

The clipping complexity information includes the combined effects of: 

• Clip path 

• Viewing limits 

• Graphics field 

• Clip region 

• Visible region (windowing considerations). 


RGN_NULL 
RGNRECT 
RGNCOM PLEX 
RGNERROR 


Null region 
Rectangular region 
Complex region 
Error. 


Possible returns from WinGetLastError 

PMERRJNVHPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_COORDINATE_OVERFLOW An internal coordinate overflow error occurred. This can 

occur if coordinates or matrix transformation elements (or 
both) are invalid or too large. 


Remarks 

Note: This function must not be used when creating SAA-conforming metafiles; see “Metafile 
Restrictions” on page G-1. 

Related Functions 

• GpiExcludeClipRectangle 

• GpilntersectClipRectangle 

• GpiQueryClipBox 

• GpiQueryClipRegion 

• GpiSetClipRegion 

• WinExcludellpdateRegion 
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GpiOffsetClipRegion - 
Offset Clip Region 

Example Code 

This example uses GpiOffsetClipRegion to move the clipping region right by 3 and up by 3. 


Idefine INCL_GPIREGIONS /* Region functions */ 
linclude <os2.h> 

LONG 1 Complexity; /* clipping complexity /error return */ 
HPS hps; /* Presentation-space handle */ 
POINTL pptlPoint = {3,3}; /* displacement */ 


IComplexity = GpiOffsetClipRegion(hps, &pptl Poi nt) ; 
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GpiOffsetElementPointer - 
Offset Element Pointer 


#define INCL_GPISEGEDITING /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiOffsetElementPointer (HPS hps, LONG loffset) 


This function sets the element pointer, within the current segment, to the current value plus the 
specified offset. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

loffset (LONG) - input 

Offset to be added to the element pointer. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An attempt was made to issue a function that is invalid in 
a micro presentation space. 

An attempt was made to issue a segment editing element 
function that is invalid when the actual drawing mode is 
not set to retain 

An attempt has been made to issue 
GpiQueryElementType or GpiQueryElement while there is 
no currently open segment. 

An attempt was made to issue a function invalid inside an 
element bracket. 


PMERR_INV_HPS 

PMERR_PS_BUSY 

PMERR_INV_MICROPS_FUNCTION 

PMERR_NOT_IN_RETAIN_MODE 

PMERR_NO_CURRENT_SEG 

PMERRJNVINELEMENT 


Remarks 

If the resulting value is negative, the element pointer is set to 0. If the resulting value is greater than 
the number of elements in the segment, it is set to the last element. 

This function is only valid when the drawing mode (see GpiSetDrawingMode) is set to retain (not 
draw-and-retaln), and a segment bracket is currently in progress. 

This function is invalid within an element bracket. 
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GpiOffsetElementPointer 
Offset Element Pointer 


Related Functions 

• GpiBeginElement 

• GpiDeleteElement 

• GpiDeleteElementRange 

• GpiDeleteElementsBetweenLabels 

• GpiElement 

• GpiEndElement 

• GpiLabel 

• GpiQueryElement 

• GpiQueryElementPointer 

• GpiQueryElementType 

• GpiSetElementPointer 

• GpiSetElementPointerAtLabel 

Example Code 

This example uses the GpiOffsetElementPointer function to move to the element associated with a 
label element. Combining the GpiSetElementPointerAtLabel and GpiOffsetElementPointer functions 
is a convenient way to locate elements in segments that have been edited. 

Idefine INCL_GPISEGEDITING /* GPI Segment Edit functions */ 

Idefine INCL_GPISEGMENTS /* Segment functions */ 

linclude <os2.h> 

HPS hps; /* presentation space handle */ 

POINTL ptl Start = { 0, 0 }; /* first vertex */ 

POINTL ptlTrianglet] = { 100, 100, 200, 0, 0, 0 }; /* vertices */ 

GpiOpenSegment(hps, 4L); /* creates a segment with labels */ 

GpiLabel (hps, 5L); GpiMove(hps, iptlStart); 

GpiLabel (hps, 10L); GpiPolyLine(hps, 3L, ptlTriangle) ; 

GpiCloseSegment(hps) ; 


GpiOpenSegment(hps, 4L); 

GpiSetElementPointerAtLabel (hps, 10L);/* move to label 10 */ 

GpiOffsetElementPointer(hps, 1L); /* move to polyline element */ 
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GpiOffsetRegion - 
Offset Region 


#define INCL_GPIREGIONS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiOffsetRegion (HPS hps, HRGN Hrgn, PPOINTL pptiOffset) 


This function moves a region. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

The region must be owned by the device identified by the currently associated device context. 

Hrgn (HRGN) - input 

Handle of the region to be moved. 

pptiOffset (PPOINTL) - input 

Offset to be added to the region boundary. 


Returns 

Success indicator: 

TRUE Successful completion 

FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERR INV HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_HRGN An invalid region handle was specified. 

PMERR_REGION_IS_CLIP_REGION An attempt was made to perform a region operation on a 

region that is selected as a clip region. 

PMERR_INV_COORDINATE An invalid coordinate value was specified. 

PMERR_HRGN_BUSY An internal region busy error was detected. The region 

was locked by one thread during an attempt to access it 
from another thread. 


Remarks 

This function moves the region to a new position. The new position is obtained by adding the value 
of pptiOffset to all the points that define the region boundary. 

An error is raised if the specified region is currently selected as the clip region (by 
GpiSetClipRegion). 
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GpiOffsetRegion 
Offset Region 


Related Functions 

• GpiCombineRegion 

• GpiCreateRegion 

• GpiDestroyRegion 

• GpiEqualRegion 

• GpiPaintRegion 

• GpiPtlnRegion 

• GpiQueryRegionBox 

• GpiQueryRegionRects 

• GpiRectlnRegion 

• GpiSetRegion 


Example Code 

This example uses GpiOffsetRegion to move a region right by 3 and up by 3. 


Idefine INCL_GPIREGIONS /* Region functions */ 

linclude <os2.h> 


BOOL fSuccess; 

/* success indicator 

*/ 

HPS hps; 

/* Presentation-space handle 

*/ 

HRGN Hrgn; 

/* handle for region 

*/ 

POINTL pptl Offset = 

{3,3}; /* displacement 

*/ 


fSuccess = GpiOffsetRegion(hps, Hrgn, &pptlOffset) ; 
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GpiOpenSegment - 
Open Segment 


#define INCL_GPISEGMENTS /* Or use INCL_GPI or INCL_PM 7 


BOOL GpiOpenSegment (HPS hps, LONG ISegment) 


This function opens a segment with the specified identification number. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

ISegment (LONG) - input 
Segment identifier. 

Must be zero or a positive number. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 


PMERRJNVHPS 

PMERRPSBUSY 

PMERRINVSEGNAME 

PMERR_INV_MICROPS_FUNCTION 

PMERRALREADYINSEG 

PMERRPATHINCOMPLETE 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid segment identifier was specified. 

An attempt was made to issue a function that is invalid in 
a micro presentation space. 

An attempt was made to open a new segment while an 
existing segment bracket was already open. 

An attempt was made to open or close a segment either 
directly or during segment drawing, or to issue 
GpiAssociate while there is an open path bracket. 


PMERR_AREAJNCOMPLETE Either: 

• A segment has been opened, closed, or drawn. 

• GpiAssociate was issued while an area bracket was 
open. 

• A drawn segment has opened an area bracket and 
ended without closing it. 

PMERR_INV_MODE_FOR_REOPEN_SEG An attempt was made to reopen an existing segment 

while the drawing mode was set to DM_DRAW or 
DM_DRAWANDRETAIN. 


PMERR DYNAMIC SEG ZEROJNV An attempt was been made to open a dynamic segment 

with a segment identifier of zero. 

PMERR_INV_MODE_FOR_OPEN_DYN An attempt was made to open a segment with the 

ATTR DYNAMIC segment set, while the drawing mode 
was set to DM_DRAW or DM_DRAWANDRETAIN. 
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GpiOpenSegment 
Open Segment 


PMERR_UNCHAINED_SEG_ZERO_INV An attempt was made to open segment with segment 

identifier zero and the ATTR_CHAINED segment attribute 
not specified. 


Remarks 

A segment is a way of grouping graphics primitives. 

If the current drawing mode is retain or draw-and-retain (see GpiSetDrawingMode), the following 
occurs: 

• If a nonzero identifier is given, and if a segment with the specified identifier does not already 
exist, a new retained segment is created. If one does already exist, it is reopened in retain 
mode (with the element pointer set to 0), but is an error in draw-and-retaln mode. 

• If an identifier of 0 is given, a new retained segment is created, regardless of whether one with a 
0 identifier already exists. There can be more than one segment with an identifier of 0, but such 
segments can never subsequently be referenced by identifier. When they have been created, 
they continue to exist until all segments are deleted. Zero segments must be chained and 
cannot be defined as dynamic. 

If the current drawing mode is draw, a new nonretained segment is started. No check is made 
against any possible retained segment identifiers. The current attributes are set to default values 
(subject to the ATTR_FASTCHAIN segment attribute; see below). 

The initial attributes of the segment are as set by GpiSetlnitialSegmentAttrs. The attributes may 
subsequently be changed with GpiSetSegmentAttrs (except for a segment with an identifier of 0). It is 
an error to try to open a new segment with a drawing mode of draw or draw-and-retaln, with the 
ATTR_DYNAMIC segment attribute. 

This function causes a segment bracket to be started. While the bracket is in effect, any primitive 
and attribute functions are considered to be part of the segment, and are stored in it if the drawing 
mode is retain or draw-and-retaln. The bracket is terminated by a GpiCloseSegment. It is an error if 
GpiOpenSegment is issued when a segment is already open. 

The following actions occur when drawing of a chained segment is started (either as it is passed 
across the API in draw or draw-and-retaln, or as it is found during a draw operation): 

• Current attributes and arc parameters are reset to default values. 

• The current tag is reset to its default value. 

• Current model transform is reset to unity. 

• Current position is set to (0,0). 

• The current clip path is set so as to cause no clipping. 

• The current viewing limits are reset to their default values. 

• The current viewing transform is set either to the value last set by 
GpiSetViewingTransformMatrix, or to the default value if no GpiSetViewingTransformMatrix 
function has been issued. 

If the segment has the ATTR_FASTCHAIN attribute, the application should not depend upon whether 
or not these operations are performed. This avoids complications when interchanging picture data 
with other implementations. 

Note: The current clip region is not changed by this function. 

If any primitive/attribute calls are issued immediately before this function (that is, outside a segment 
bracket), then any currently open area, path, or element brackets are terminated, as described for 
GpiCloseSegment, before the new segment is opened. 

If the segment being defined is to be called from another segment (see GpiCallSegmentMatrix), 
ensure that the viewing transform (see GpiSetViewingTransformMatrix) is unity before first opening 
the segment. 
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Open Segment 


The maximum number of retained segments allowed for a given presentation space at any time is 
16378. 

Related Functions 

• GpiCallSegmentMatrix 

• GpiCloseSegment 

• GpiCorrelateSegment 

• GpiDeleteSegment 

• GpiDeleteSegments 

• GpiDrawSegment 

• GpiErrorSegmentData 

• GpiQuerylnitialSegmentAttrs 

• GpiQuerySegmentAttrs 

• GpiQuerySegmentNames 

• GpiQuerySegmentPriority 

• GpiSetlnitialSegmentAttrs 

• GpiSetSegmentAttrs 

• GpiSetSegmentPriority 

• GpiSetViewingTransformMatrix 

Example Code 

This example uses the GpiOpenSegment to create a new segment. The segment is subsequently 
drawn by using the GpiDrawSegment function. 


Idefine INCL_GPISEGMENTS /* Segment functions */ 
linclude <os2.h> 

HPS hps; /* presentation space handle */ 
POINTL ptl Start = { 0, 0 }; /* first vertex */ 
POINTL ptlTrianglet] = { 100, 100, 200, 0, 0, 0 }; /* vertices */ 

GpiOpenSegment (hps, 1L); /* opens the segment */ 
GpiMove(hps, SptlStart); /* moves to starting point (0,0) */ 
GpiPolyLine(hps, 3L, ptlTriangle) ;/* draws triangle */ 
GpiCloseSegment (hps) ; /* closes the segment */ 


GpiDrawSegment (hps, 1L); 
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GpiOutlinePath 
Outline Path 


#define INCL_GPIPATHS /* Or use INCL_GPI or INCL_PM */ 


LONG GpiOutlinePath (HPS hps, LONG IPath, LONG lOptions) 


This function draws the outline of a path. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

IPath (LONG) - input 

Identifier of path to be outlined; it must be 1. 

lOptions (LONG) - input 
Options: 

Reserved; must be 0. 

Returns 

Correlation and error indicators: 

GPI_OK Successful 

GPI_HITS Correlate hits 

GPI_ERROR Error. 

Possible returns from WinGetLastError 

PMERRINVHPS 
PMERR_PS_BUSY 

PMERR_INV_PATH_ID 
PMERRJNV RESERVEDFIELD 
PMERRPATHUNKNOWN 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid path identifier parameter was specified. 

An invalid reserved field was specified. 

An attempt was made to perform a path function on a path 
that did not exist. 


Remarks 

The outline of the path is drawn, using the line attributes, including cosmetic line width (see 
GpiSetLineWidth) but not geometric line width (see GpiSetLineWidthGeom). This normally has the 
same effect as if the lipes, curves, and so on, which comprise the path, had been drawn without 
defining them as being within a path. However, if character strings (referencing outline fonts) are 
contained within the path, the outlines of the characters, without the interior fill, are drawn by 
GpiOutlinePath, giving the appearance of hollow characters. 

Open figures within the path are not closed automatically. 

When the outline of the path has been drawn, the path is deleted. 
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GpiOutlinePath - 
Outline Path 


Related Functions 

• GpiBeginPath 

• GpiEndPath 

• GpiFillPath 

• GpiModifyPath 

• GpiPathToRegion 

• GpiSetClipPath 

• GpiStrokePath 

• GpiSetLineEnd 

• GpiSetLineJoin 

• GpiSetLineType 

• GpiSetLineWidth 

• GpiPop 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiSetBackColor 

• GpiSetBackMix 

• GpiSetColor 

• GpiSetMix 

Graphic Elements and Orders 

Element Type: OCODE_GOPTH 
Order: Outline Path 


Example Code 

This example uses GpiOutlinePath to draw the outline of a path (in this case a triangle). 


Idefine INCL_GPIPATHS /* Path functions */ 
linclude <os2.h> 

LONG lHits; /* correlation/error indicator */ 
HPS hps; /* Presentation-space handle */ 
POINTL ptl Start = { 0, 0 }; /* first vertex */ 


POINTL ptlTriangle[] = { 100, 100, 200, 0, 0, 0 }; /* vertices */ 


GpiBeginPath (hps, 1L); 

GpiMove(hps, iptlStart); 
GpiPolyLine(hps, 2L, ptlTriangle) ; 
GpiCloseFigure(hps) ; 
GpiEndPath(hps) ; 


/* start the path bracket */ 
/* move to starting point */ 
/* draw the three sides */ 
/* close the triangle */ 
/* end the path bracket */ 


1 Hits = GpiOutlinePath(hps, 1L, 0L); 
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Paint Region 


#define INCL_GPIREGIONS /* Or use INCL_GPI or INCL_PM */ 


LONG GpiPaintRegion (HPS hps, HRGN hrgn) 


This function paints a region into a presentation space, using the current pattern attributes. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

hrgn (HRGN) - input 
Region handle. 


Returns 

Correlation and error indicators: 

GPI_OK Successful 

GPI_HITS Correlate hits 

GPI_ERROR Error. 

An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An attempt was made to perform a region operation on a 
region that is selected as a clip region. 

An invalid region handle was specified. 

An internal region busy error was detected. The region 
was locked by one thread during an attempt to access it 
from another thread. 


Possible returns from WinGetLastError 

PMERRJNVHPS 
P M E R R_PS_BUS Y 

PMERRREGIONJSCLIPREGION 

PMERRINVHRGN 

PMERRHRGNBUSY 


Remarks 

The current GPI area foreground and background colors are used. Mixing is controlled by the area 
foreground mix only. 

It is invalid if the specified region is currently selected as the clip region (by GpiSetClipRegion). 
The region is assumed to be defined in device coordinates. 

Note: This function must not be used when creating SAA-conforming metafiles; see “Metafile 
Restrictions” on page G-1. 
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Paint Region 


Related Functions 

• GpiBeginArea 

• GpiBeginPath 

• GpiFillPath 

• WinFillRect 

• GpiCombineRegion 

• GpiCreateRegion 

• GpiDestroyRegion 

• GpiEqualRegion 

• GpiOffsetRegion 

• GpiPtlnRegion 

• GpiQueryRegionBox 

• GpiQueryRegionRects 

• GpiRectlnRegion 

• GpiSetRegion 

• GpiPop 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiSetBackColor 

• GpiSetBackMix 

• GpiSetColor 

• GpiSetMix 

• GpiSetPattern 

• GpiSetPatternRefPoint 

• GpiSetPatternSet 

Example Code 

This example uses the GpiPaintRegion function tofill a complex region consisting of three, 
intersecting rectangles. The region is filled with a red, diagonal pattern. 

Idefine INCL_GPIREGIONS /* Region functions */ 

linclude <os2.h> 

HPS hps; /* presentation space handle */ 

HRGN hrgn; /* handle for region */ 

RECTL arcl [3] = { 100, 100, 200, 200, 

150, 150, 250, 250, 

200, 200, 300, 300 }; 

hrgn = GpiCreateRegion (hps, 3L, arcl); 

GpiSetColor(hps, CLR_RED); 

GpiSetPattern (hps, PATSYM_DIAG1) ; 

GpiPaintRegion(hps, hrgn); 


/* 1st rectangle */ 
/* 2nd rectangle */ 
/* 3rd rectangle */ 
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Partial Arc 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


LONG GpiPartialArc (HPS hps, PPOINTL pptICenter, FIXED fxMultlplier, FIXED fxStartAngle, 
FIXED fxSweepAngle) 


This function draws a straight line, followed by an arc. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

pptICenter (PPOINTL) - input 
Center point. 

Center of the arc. 

fxMultlplier (FIXED) - input 
Multiplier. 

This determines the size of the arc in relation to an arc with the current arc parameters. 

The implementation limit for the multiplier is 255. 

The value must not be negative. 

fxStartAngle (FIXED) - input 
Start angle in degrees. 

The value must be positive. 

fxSweepAngle (FIXED) - input 
Sweep angle in degrees. 

The value must be positive. 

Returns 

Correlation and error indicators: 

GPI_OK Successful 

GPI_HITS Correlate hits 

GPI_ERROR Error. 

Possible returns from WinGetLastError 

PMERRJNVHPS 
PMERRPSBUSY 

PMERRINVMULTIPLIER 

PMERRINVCOORDINATE 
PMERRINVANGLEPARM 

PMERRINVNESTEDFIGURES 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid multiplier parameter was specified with 
GpiPartialArc or GpiFullArc. 

An invalid coordinate value was specified. 

An invalid angle parameter was specified with 
GpiPartialArc. 

Nested figures have been detected within a path 
definition. 
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Partial Arc 


Remarks 

This function draws two figures: 

• A straight line, from the current position to the starting point of an arc 

• An arc, with its center at the specified point. 

The full arc, of which the arc is a part, is identical to that defined by GpiFullArc. The part of the arc 
drawn by this primitive is defined by the parameters fxStartAngle and fxSweepAngle, that are the 
start and sweep angles, subtended from the center, if the current arc parameters specify a circular 
form. If they do not, these angles are skewed to the same degree that the ellipse is a skewed circle. 
fxStartAngle is measured counterclockwise from the x axis of the circle before application of the arc 
parameters. Both angles must be positive; whether the arc is drawn clockwise or counterclockwise 
is determined by the arc parameters. 

Current position is updated to the final point on the arc. 

Note: This differs from GpiFullArc, where current position remains at the center of the figure. A 
primitive (such as GpiLine) following GpiPartialArc draws from the end point of the arc. 

A segment of a pie can be drawn by the following calling sequence: 

1. GpiMove, to center of pie 

2. GpiPartialArc, drawing one spoke and the arc 

3. GpiLine, back to center. 

The third step can be performed implicitly by autoclosure if an area is being drawn. 

A closed figure bounded by a chord and an arc can be drawn by the following calling sequence: 

1. GpiSetLineType to invisible 

2. GpiPartialArc, with fxStartAngle = angle2, and fxSweepAngle = 0, to define one end of the chord 

3. GpiSetLineType to visible 

4. GpiPartialArc, with fxStartAngle = anglel , and fxSweepAngle = angle2 - anglel . 

(In the second example, angle2 is greater than anglel. If the interior of the chord is to be shaded, the 
area must start after step 2 or 3.) 

A sweep angle of greater than 360 degrees is valid, and means that after the initial line a full arc is 
drawn, followed by a partial arc with a sweep angle of ( fxSweepAngle MOD 360) degrees. 


Related Functions 

• GpiFullArc 

• GpiPointArc 

• GpiSetArcParams 

• GpiSetDefArcParams 

• GpiSetLineType 

• GpiSetLineWidth 

• GpiPop 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetLineEnd 

• GpiSetLineJoin 

• GpiSetLineType 

• GpiSetLineWidth 

• GpiSetLineWidthGeom 

• GpiSetDefAttrs 

• GpiSetBackColor 

• GpiSetBackMix 

• GpiSetColor 

• GpiSetMix 
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GpiPartialArc 
Partial Arc 


Graphic Elements and Orders 

Element Type: OCODE_GCPARC 
Order: Partial Arc at Current Position 


Example Code 

This example uses the GpiPartialArc function to draw a chord (an arc whose end points are 
connected by a straight line). 

Idefine INCL_GPIPRIMITIVES /* GPI primitive functions */ 
linclude <os2.h> 

HPS hps; /* presentation space handle */ 

POINTL ptl = { 100, 100 }; /* center point for arc */ 

Gpi Set Li neT ype ( hps , LINETYPEJNVISIBLE) ; 

GpiPartialArc (hps, &ptl , MAKEFIXED(50, 0), MAKEFIXED(0, 0), 

MAKEFIXED(180, 0)); 

Gpi SetLi neType (hps , LINETYPE_SOLID) ; 

Gpi Partial Arc (hps, &ptl , MAKEFIXED(50, 0), MAKEFIXED(0, 0), 

MAKEFIXED(180, 0)); 
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Path to Region 


#define INCL_GPIPATHS /* Or use INCL_GPI or INCL_PM */ 


HRGN GpiPathToRegion (HPS hps, LONG IPath, ULONG fiOptlons) 


This function converts a path to a region. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

IPath (LONG) - input 

Identifier of path to be converted; it must be 1. 

fiOptlons (ULONG) - input 
Fill options: 

FPATH_ALTERNATE Fills the path using the alternate rule; see GpiBeginArea. 

FPATH WINDING Fills the path using the winding rule; see GpiBeginArea. This value must 
be selected if the path has been modified using GpiModifyPath. 

The default is FPATH_ALTERNATE. 

Returns 

Region handle: 

^0 Region handle 

RGN_ERROR Error. 

Possible returns from WinGetLastError 

PMERRINVHPS 
PMERRPSBUSY 

PMERR_INV_PATH_ID 
PMERR_INV_PATH_CONVERT_OPTIONS 

PMERRPATHUNKNOWN 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid path identifier parameter was specified. 

An invalid options parameter was specified with 
GpiOutlinePath. 

An attempt was made to perform a path function on a path 
that did not exist. 


Remarks 

This function converts a path (originally defined by a series of GPI drawing calls) to a region. The 
new region can be operated on by the GPI region calls; in particular GpiCombineRegion can be used 
to combine it with another region. 

Any open figures within the path are closed automatically. 

The boundaries of the area defined by the path are considered to be part of the interior, so that a 
point on the boundary is included in the new region. 

After a path is converted to a region, it no longer exists as a path. The path cannot be reused for any 
other purpose. 
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GpiPathToRegion 
Path to Region 


Related Functions 

• GpiBeginPath 

• GpiCombineRegion 

• GpiEndPath 

• GpiFillPath 

• GpiModifyPath 

• GpiOutlinePath 

• GpiSetClipPath 

• GpiStrokePath 

Example Code 

This example uses GpiPathToRegion to convert a path (a triangle) to a region using the winding rule 
to fill the region. 


Idefine INCL_GPIPATHS /* Path functions */ 
linclude <os2.h> 

HRGN hrgn; /* handle for region */ 
HPS hps; /* Presentation-space handle */ 
POINTL ptlStart = { 0, 0 }; /* first vertex */ 


POINTL ptlTriangle[] = { 100, 100, 200, 0, 0, 0 }; /* vertices */ 

GpiBeginPath(hps, 1L); /* start the path bracket */ 

GpiMove(hps, &ptlStart); /* move to starting point */ 

GpiPolyLine(hps, 2L, ptlTriangle); /* draw the three sides */ 

GpiCloseFigure(hps) ; /* close the triangle */ 

GpiEndPath(hps) ; /* end the path bracket */ 

hrgn = GpiPathToRegion(hps, 1L, FPATH WINDING) ; 
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GpiPlayMetaFile - 
Play Metafile 

#define INCL_GPIMETAFILES /* Or use INCL_GPI or INCL_PM */ 


LONG GpiPlayMetaFile (HPS hps, HMF hmf, LONG ICountl, PLONG alOptarray, 
PLONG pISegCount, LONG ICount2, PSZ pszDesc) 


This function plays a metafile into a presentation space. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

hmf (HMF) - input 
Metafile handle. 

Handle of the metafile containing the data. 

ICountl (LONG) - input 

Count of elements in alOptarray. 

alOptarray (PLONG) - input 
Array of options for playing. 

The values of the elements in this array determine what action is to be taken when the metafile 
is played into the specified presentation space. The elements in the array are numbered 
consecutively, starting with PMF_SEGBASE. The element number constants start with 0. (Refer 
to the appropriate bindings reference.) Any elements in the array that are not set to one of the 
values defined below must be set to 0. 

Optarray.[PMF SEGBASE] Reserved; must be 0. 

Optarray.[PMF_LOADTYPE] Specifies what transformations should be performed on 

the imported picture. The options are: 

LTJJEFAULT The default; same as LT_NOMODIFY 

LT_NOMODIFY The graphics are restored using the 
current viewing transform (see 
GpiSetViewingTransformMatrix), rather than the ones 
that were in use when the data was created. This is 
the default action. 

Any change to the graphics field or default viewing 
transform during the course of the picture will be 
ignored if this option is specified (or defaulted). 

LT_ORIGINALVIEW The graphics are restored using the 
viewing transforms that are in the metafile. 

The default viewing transform of the presentation 
space is not altered (unless RES_RESET is specified). 
However, any changes to the default viewing 
transform that occur during the course of the picture 
(and also any graphics field clipping) cause changes 
to the values in the presentation space. 

Optarray.[PMF_RESOLVE] Reserved; must be 0. 

Optarray.[PMF LCIDS] Specifies the action to be taken for any logical font 

definitions, or bit maps referenced by local identifiers 
for use as shading patterns that are held in the metafile. 

The options are: 
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GpiPlayMetaFile 
Play Metafile 


Optarray.[PMF_RESET] 


Optarray.[PMF_SUPPRESS] 


LC DEFAULT Default; same as LC_NOLOAD. 

LC NOLOAD Do not load such objects. This is the 
default, and is used where the application expects the 
correct objects to be already loaded. 

LC_LOADDISC Load all objects referenced in the 
metafile, first deleting any already existing in the 
presentation space, for which the referenced local 
identifier is already in use. 

Specifies whether the presentation space should be 
reset before playing the metafile, with the page units 
and size being set as defined in the metafile. 

The options are: 

RES_DEFAULT Default; same as RES_NORESET. 

RES NORESET Do not perform a reset. 

RES_RESET Reset the presentation space, before 
loading any logical fonts, color tables, segments, and 
so on, as follows: 

1. Reset the page units and page size to the values 
contained In the metafile. 

2. Set up default transformations, based on the 
page units and size, as if the presentation space 
had just been created with these values. 

3. Further modify the device transform to ensure 
that the physical size of the metafile picture is 
preserved. (Only performed if the page units in 
the metafile are not PU_ARBITRARY or 
PU_PELS.) 

4. Perform the equivalent of GpiResetPS (option 
GRES_ALL). 

5. Set the default viewing transform to the value 
specified in the metafile. 

This option should normally be used with a 
PMF_LOADTYPE option of LT_ORIGINALVIEW and 
LC_LOADDISC, but this is not enforced. 

Specifies whether the playing of this metafile actually 
occurs. This is provided to allow an application to use 
the PMF_RESET option, and then to regain control to 
perform further presentation-space modifications if 
necessary, before playing the remainder of the metafile. 

The options are: 

SUP_DEFAULT Default; same as SUP_NOSUPPRESS. 

SUP NOSUPPRESS Do not suppress the remainder of 
the metafile. 

SUP_SUPPRESS Suppress the remainder of the 
metafile. 

If this option is selected, only processing as 
determined by the PMF_RESET option is performed. 
The remainder of the metafile, and all other options, 
are ignored. 
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Play Metafile 


Optarray.[PMF_COLORTABLES] Specifies the action to be taken with respect to any color 

table or palette implied or present within the metafile. 

The options are: 

CTAB_DEFAULT Default; same as CTAB_NOMODIFY. 

CTAB NOMODIFY Ignore. The default or loaded color 
table or selected palette in the presentation space is 
unchanged, as are the references to color attributes 
in the new data. This is the default; it is suitable 
where it is known that the currently loaded color table 
or selected palette (if any) is suitable for the use of 
color in the imported picture. 

CTAB_REPLACE Overwrite the currently-loaded color 
table (if any), with a color table as implied or present 
in the metafile. This can be used where there is no 
existing picture. 

CT AB_REPLACEP ALETTE Overwrite the 

currently-selected palette (if any), with a palette as 
implied or present in the metafile. This can be used 
where there is no existing picture. 

Note: If the metafile specifies a color table in RGB 
mode, the currently-selected palette (if any) is 
overwritten with a color table in RGB mode, 
and a warning is issued. 

Optarray.[PMF_COLORREALIZABLE] Specifies whether the color table data contained in the 

metafile should be loaded with the LCOL_REALIZABLE 
option or not (see GpiCreateLogColorTable). 

The options are: 

CREA_DEFAULT Default; same as CREA_NOREALIZE 

CREADOREALIZE Load the color table with the 
realizable option set, and realize the color table. 

CREA_NOREALIZE Load the color table with the 
realizable option off. This is the default. 

Optarray.[PMF_DEFAULTS] Specifies how the drawing defaults contained in the 

metafile should be used (see GpiSetDefAttrs, 
GpiSetDefViewingLimits, GpiSetDefTag, and 
GpiSetDefArcParams). 

The options are: 

DDEF_DEFAULT Default; same as DDEFJGNORE 

DDEF IGNORE Ignore any drawing default values in the 
metafile. 

DDEF LOADDISC Change any drawing default values in 
the presentation space that are specified in the 
metafile, to the values contained in the metafile. 

pISegCount (PLONG) - output 

Reserved. 

The value 0 is always returned. 

ICount2 (LONG) - input 

Count of bytes in pszDesc. 
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Play Metafile 


pszDesc (PSZ) - output 
Descriptive record. 

pszDesc is a buffer that, on return, contains the descriptive record, of up to 253 bytes, that is 
saved when the metafile is created (see DevOpenDC). This is null-terminated, even if it has to 
be truncated. 


Returns 

Correlation and error indicators: 

GPI_OK Successful 
GPI_HITS Correlate hits 
GPI_ERROR Error. 


Possible returns from WinGetLastError 


PMERRJNVHPS 

PMERR_PS_BUSY 

PMERRINVHMF 

PMERR_INV_LENGTH_OR_COUNT 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid metafile handle was specified. 

An invalid length or count parameter was specified. 


P M E R RJN V_PLA Y_M ETAFILE_OPTION An invalid option parameter was specified with 

GpiPlayMetaFile. 

PMERR_INCOMPATIBLE_METAFILE An attempt was made to associate a presentation space 

and a metafile device context with incompatible page 
units, size or coordinate format; or to play a metafile 
using the RES_RESET option (to reset the presentation 
space) to a presentation space that is itself associated 
with a metafile device context. 


PMERR_INV_METAFILE 

PMERRINVMICROPSORDER 

PM ER R_ST OP_DRAW_OCCU RRED 

PMERRINVOUTSIDEDRAWMODE 

PMERRINVELEMENTPOINTER 

PMERRINVINCURRENTEDITMODE 

PMERRPROLOGERROR 

PMERRDUPSEG 


An invalid metafile was specified with GpiPlayMetaFile. 

An attempt was made to play a metafile containing orders 
that are invalid in a micro presentation space. 

Segment drawing or GpiPlayMetaFile was stopped 
prematurely in response to a GpiSetStopDraw request. 

An attempt was made to issue a GpiSavePS or 
GpiRestorePS function, or an output only function (for 
example, GpiPaintRegion) from GpiPlayMetaFile without 
the drawing mode set to DM DRAW. 

An attempt was made to issue GpiPutData with the 
element pointer not pointing at the last element. 

An attempt was made to issue a function invalid inside 
the current editing mode. 

A prolog error was detected during drawing. Segment 
Prologs are used internally within retained segments and 
also appear in metafiles. This error can also arise from 
an End Prolog order that is outside a prolog. 

During GpiPlayMetaFile, while the actual drawing mode 
was draw-and-retain or retain, a metafile segment to be 
stored in the presentation space was found to have the 
same segment identifier as an existing segment. 
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Play Metafile 


Remarks 

This function executes the contents of a metafile. This process is known as “playing” the metafile. 
Whether the graphics are drawn, or retained in segment store, or both, depends upon the current 
drawing mode (see GpiSetDrawingMode) in the presentation space, for the chained and unchained 
segment contexts, as appropriate. If chained segments are retained, they are added to the end of 
any existing segment chain. An error is raised if a segment is to be retained, and it has the same 
(nonzero) identifier as a currently existing segment. 

A segment must not be open when this function is issued. At the completion of the call, there is no 
open segment. 

The application may need to reset the presentation space by GpiResetPS, before issuing this 
function. Alternatively, the PMF RESET option on this function may be suitable. 

Segments retain the segment attributes that they originally possessed. 


Related Functions 

• GpiCopyMetaFile 

• GpiDeleteMetaFile 

• GpiLoadMetaFile 

• GpiQueryMetaFileBits 

• GpiQueryMetaFileLength 

• GpiSaveMetaFile 

• GpiSetMetaFileBits 
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Play Metafile 


Example Code 

This example uses the GpiPlayMetaFile function to play (execute) the metafile loaded by 
GpiLoadMetaFile into a presentation space associated with a window. GpiPlayMetaFile is called 
twice: the first call resets the presentation space (by combining the RES_RESET and SUP_SUPPRESS 
flags), while the second call actually executes the metafile. 


Idefine INCL_GPIMETAFILES /* Metafile functions */ 
Idefine INCL_GPICONTROL /* GPI control Functions */ 
linclude <os2.h> 


HAB 

HPS 

HMF 

HDC 

HWND 

SIZEL 

CHAR 

LONG 


hab; 

hps; 

hmf; 

hdc; 

hwnd; 

s i zl ={0 , 0} ; 
szBuffer[80] ; 


/* 

/* 

/* 

/* 

/* 

/* 

/* 

/* 


anchor-block handle 
presentation space handle 
metafile handle 
Device-context handle 
window handle 

use same page size as device 
descriptive record buffer 
correlation/error indicator 
7 


lHits; 

/* play metafile options array 
LONG optArray [PMF_DEFAULTS+1] = 

{0 , LT_DEFAULT , 0 , LC_DEFAULT , RES_RESET, 

SUP_SUPPRESS,CTAB_DEFAULT,CREA_DEFAULT, 

DDEF_DEFAULT}; 


/ 

/ 

/ 

/ 

/ 

/ 

/ 

/ 


hmf = GpiLoadMetaFile (hab, "sample. met") ; 

/* create window device context and presentation space, 
associating DC with the PS */ 
hdc = WinOpenWindowDC(hwnd) ; 

hps = GpiCreatePS(hab, hdc, &sizl, PU_PELS | GPIA_ASSOC); 


/* reset presentation space */ 

lHits = GpiPlayMetaFile(hps, hmf, 9L, optArray, (LONG *)0, 80L, 
szBuffer) ; 


/* display metafile in window (reset and 
suppress flags must be changed) */ 
optArray [PMF_SUPPRESS]=SUP_DEFAULT ; 
opt Array [PMF_RESET] =RES_DEFAULT ; 

lHits = GpiPlayMetaFile (hps, hmf, 9L, optArray, (LONG *)0, 80L, 
szBuffer) ; 
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Point Arc 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


LONG GpiPointArc (HPS hps, PPOINTL aptiPoints) 


This function creates an arc, using the current arc parameters, through three points, starting at the 
current position. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

aptiPoints (PPOINTL) - input 
Intermediate and end points. 


Returns 

Correlation and error indicators: 

GPI_OK Successful 

GPI_HITS Correlate hits 

GPI_ERROR Error. 

An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid coordinate value was specified. 

Nested figures have been detected within a path 
definition. 


Possible returns from WinGetLastError 

PMERRJNVHPS 

PMERR_PS_BUSY 

PMERRJNVCOORDINATE 

PMERRINVNESTEDFIGURES 


Remarks 

The first element of the aptiPoints array defines an intermediate point along the arc, and the second 
element identifies the end point of the arc. Upon completion, current position is set to the end point 
of the arc. 

Related Functions 

• GpiFullArc 

• GpiPartialArc 

• GpiSetArcParams 

• GpiSetDefArcParams 

• GpiSetLineType 

• GpiSetLineWidth 

• GpiPop 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiSetBackColor 

• GpiSetBackMix 

• GpiSetColor 

• GpiSetMix 
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GpiPointArc 
Point Arc 


Graphic Elements and Orders 

Element Type: OCODE_GCARC 
Order: Arc at Current Position 


Example Code 

This example uses the GpiPointArc function to draw an arc through the three points of a triangle. 
The GpiPolyLine function then draws the triangle. 

Idefine INCL_GPI PRIMITIVES /* GPI primitive functions */ 

linclude <os2.h> 

HPS hps; /* presentation space handle */ 

POINTL ptlTrianglet] = { 0, 0, 100, 100, 200, 0 }; 

GpiMove(hps, &ptlTriangle[0]) ; /* moves to start point (0, 0)*/ 

GpiPointArc (hps, &ptlTriangle[l] ) ;/* draws the arc */ 

GpiMove(hps, &pt 1 T ri angle [0] ) ; /* moves to start point (0, 0)*/ 

/* draws the triangle */ 

Gpi PolyLine(hps , 3L, &ptl Tri angl e[l] ) ; 
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Polyfillet 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


LONG GpiPolyFillet (HPS hps, LONG ICount, PPOINTL apllPoInts) 


This function draws a curve starting at the current position and defined by the points supplied. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

ICount (LONG) - input 
Number of points. 

Must not be negative. Zero is valid but causes no output. 

aptIPoInts (PPOINTL) - input 
Array of points. 


Returns 

Correlation and error indicators: 

GPI_OK Successful 

GPI_HITS Correlate hits 

GPI_ERROR Error. 

An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid length or count parameter was specified. 

An invalid coordinate value was specified. 

Nested figures have been detected within a path 
definition. 


Possible returns from WinGetLastError 

PMERRINVHPS 

PMERRPSBUSY 

PMERR_INV_LENGTH_OR_COUNT 

PMERRINVCOORDINATE 

PMERRJNVNESTEDFIGURES 


Remarks 

If two points are supplied, an imaginary straight line is drawn from the current position to the first 
point and a second straight line from the first point to the second. A curve is then constructed, 
starting at the current position and tangential to the first straight line. The curve is drawn such that it 
reaches the last point at a tangent to the second straight line. Figure 5-1 on page 5-202 shows the 
curve constructed, given current position A and the two points B and C. 

If more than two points are supplied, a series of imaginary straight lines is constructed through them 
(as in the GpiPolyLine function). All of the straight lines except the first and last are then divided in 
two at their mid-points. A series of curved fillets is then drawn, each starting at the end point of the 
last, at one of the mid-points. Figure 5-2 on page 5-202 shows the curve constructed, given current 
position A and three points B, C, and D. 

The current position is set to the last point. 

Each individual fillet always lies within the area bounded by the start, end, and control points. 

It is not an error for any of the points to be coincident. 
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GpiPolyFillet - 
Polyfillet 


The maximum number of fillets allowed in the polyfillet is more than 4 000. 


A 



Figure 5-1. GpiPolyFillet Example A 


A 



Figure 5-2. GpiPolyFillet Example B 


Related Functions 

• GpiPointArc 

• GpiPolyFilletSharp 

• GpiPolySpline 

• GpiSetArcParams 

• GpiSetDefArcParams 

• GpiSetLineType 

• GpiSetLineWidth 

• GpiPop 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiSetBackColor 

• GpiSetBackMix 

• GpiSetColor 

• GpiSetMix 
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GpiPolyFillet - 
Polyfillet 


Graphic Elements and Orders 

Element Type: OCODE_GCFLT 
Order: Fillet at Current Position 

As many of these orders are generated as is necessary to hold the specified fillets. 

Example Code 

This example uses the GpiPolyFillet function to draw a curve with a loop. The four points are the 
four points of a rectangle. The curve is drawn from the lower-left corner, through the midpoint of the 
top edge, and back to the lower-right corner. 

Idefine INCL_GPIPRIMITIVES /* GPI primitive functions */ 
linclude <os2.h> 

HPS hps; /* presentation space handle */ 

POINT! ptl Start = { 0, 0 }; /* start point */ 

POINTL aptl [3] = { 200, 100, 0, 100, 200, 0 }; /* curve points */ 

GpiMove(hps, &ptl Start ) ; /* move to the lower-left corner */ 

GpiPolyFillet(hps, 3L, aptl); /* draw the curve */ 
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G piPoly Fill etSharp 
Polyfillet Sharp 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


LONG GpIPolyFllletSharp (HPS hps, LONG ICount, PPOINTL aptIPoInts, PFIXED afxSharpness) 


This function creates a fillet on a series of connected lines, with the first line starting at the current 
position. Subsequent points identify the end points of the lines. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

ICount (LONG) - input 
Count of points. 

This is the number of points specified in aptIPoints. It must be 2*1, where f is the number of 
fillets; the value must be a positive even number. Zero is valid but causes no output. 

aptIPoints (PPOINTL) - input 
An array of points. 

These points are set as follows: 

cl, el, c2, e2, c3, e3, ... cf, ef 

where: 

cf is the control point for the f'th f ill et 
ef is the end point of the f'th fillet. 

afxSharpness (PFIXED) - input 
Array of sharpness values. 

These give the sharpness of successive fillets. 


Returns 

Correlation and error indicators: 
GPI_OK Successful 

GPI_HITS Correlate hits 

GPI_ERROR Error. 


Possible returns from WinGetLastError 

PMERRINVHPS 

PMERRPSBUSY 

PMERR_INV_LENGTH_OR_COUNT 

PMERRINVCOORDINATE 

PMERRINVSHARPNESSPARM 

PMERRINVNESTEDFIGURES 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid length or count parameter was specified. 

An invalid coordinate value was specified. 

An invalid sharpness parameter was specified with 
GpiPolyFilletSharp. 

Nested figures have been detected within a path 
definition. 
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GpiPolyFilletSharp - 
Polyfillet Sharp 


Remarks 

The first fillet is drawn using the two imaginary lines, one from current position to its control point 
(the first point specified in aptIPoints), and one from this point to the second point specified in 
aptIPoints. The fillet starts from current position, and ends at this second point. It is tangential to the 
first line at current position, and to the second line at the second point of aptIPoints. The sharpness 
of this fillet is given by the first element of the afxSharpness array. 

Each subsequent fillet is drawn starting from the end point of the previous fillet, and uses the next 
two lines in the sequence, in a similar way. Therefore two points and one sharpness value are 
required for each fillet. 

The differences from GpiPolyFillet are: 

• The sharpness of each fillet is explicitly specified. 

• Both the control and the end point of each fillet are explicitly specified. 

• Adjacent fillets, generally, have a discontinuity in gradient, unless the points are chosen so that 
this is not the case. 

The sharpness of each fillet is defined as follows. Let A and C be the start and end points, 
respectively, of the fillet, and let B be the control point. (See Figure 5-3.) Let W be the mid-point of 
AC. Let D be the point where the fillet intersects WB. 

sharpness = WD/DB 

so that 

>1.0 means a hyperbola is drawn 
= 1.0 means a parabola is drawn 
<1.0 means an ellipse is drawn. 


A 



Figure 5-3. GpiPolyFilletSharp Example 

On completion, the current position is the end point of the last line in the series. Each individual fillet 
always lies within the area bounded by the start, end, and control points. 

It is not an error for any of the points to be coincident. 

The maximum number of fillets allowed is more than 2 000. 
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GpiPolyFilletSharp 
Polyfillet Sharp 


Related Functions 

• GpiPointArc 

• GpiPolyFillet 

• GpiPolySpline 

• GpiSetArcParams 

• GpiSetDefArcParams 

• GpiSetLineType 
• . GpiSetLineWidth 

• GpiPop 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiSetBackColor 

• GpiSetBackMix 

• GpiSetColor 

• GpiSetMix 

Graphic Elements and Orders 

Element Type: OCODE_GCSFLT 
Order: Sharp Fillet at Current Position 

As many of these orders are generated as is necessary to hold the specified fillets. 

Example Code 

This example uses the GpiPolyFilletSharp function to draw a curve with a loop. The curve is drawn 
within a rectangle. The sharpness values are chosen to draw the curve close to the control points. 


fdefine INCL_GPIPRIMITIVES /* GPI primitive functions */ 
linclude <os2.h> 

HPS hps; /* presentation space handle */ 

POINTL ptl Start = { 0, 0 }; /* start of curve */ 

POINTL aptl [4] ={ 100, 100, 200, 100, 0, 100, 200, 0};/* points */ 
FIXED afx[2]={MAKEFIXED(4, 0), MAKEFIXED(4, 0)};/* sharpness */ 

GpiMove(hps, &ptlStart); /* move to first starting point */ 

GpiPolyFilletSharp (hps, /* presentation-space handle */ 

4L, /* 4 points in the array */ 

aptl, /* address of array of points */ 


afx); /* address of array of sharpness values */ 
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GpiPolygons - 
Draw Polygons 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


LONG GpiPolygons (HPS hps, LONG ICount, PPOLYGON aiPolygons, LONG lOptlons, 
LONG Imodel) 


This function draws a set of closed polygons. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

ICount (LONG) - input 
Number of polygons. 

Equal to the number of polygons in the polygons array. May be zero or positive, zero causes no 
output. 

aiPolygons (PPOLYGON) - input 
Array of polygons. 

An array of POLYGON structures. 

lOptlons (LONG) - input 
Drawing options. 

This contains fields of option bits. For each field, one value should be selected (unless the 
default is suitable). These values can be ORed together to determine whether to draw boundary 
lines as well as the area interior: 

POLYGON_NOBOUNDARY Do not draw boundary I ines 
POLYGON BOUNDARY Draw boundary lines (the default). 

Construction of the area interior: 

POLY GON_ALTERNATE Construct interior in alternate mode (the default) 

POLYGON_WINDING Construct interior in winding mode. 

Imodel (LONG) - input 
Drawing model. 

POLYGONJNCL The fill is inclusive of bottom right. This is the default. 

POLYGON_EXCL The fill is exclusive of bottom right. This is provided to aid migration from 
other graphics models. 
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GpiPolygons - 
Draw Polygons 


Returns 

Correlation/error indicator: 

GPI_OK Successful 

GPI_HITS Correlate hits. 

GPI_ERROR Error. 

Possible returns from WinGetLastError 

An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid options parameter was specified with 
GpiBeginArea. 

An attempt was made to issue a function invalid inside a 
path bracket. 

An attempt was made to begin a new area while an 
existing area bracket was already open. 


PMERR_INV_HPS 

PMERRPSBUSY 

PMERRJNV AREA CONTROL 

PMERR_INV_IN_PATH 

PMERRALREADYINAREA 


Remarks 

The polygons are filled using the current AREABUNDLE structure values. For the first polygon, the 
current position is the first point. For all subsequent polygons all points which define the polygon are 
given explicitly. The polygons are automatically closed, if necessary, by drawing a line from the last 
vertex to the first. 

The polygons may overlap, but that is not necessary. 

GpiPolygons is not valid inside of an area. 


Graphic Elements and Orders 

Element Type: OCODE_GPOLYS 
Order: Polygons 


5-208 


PM Programming Reference 



GpiPolyLine - 
Polyline 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM. Also in COMMON section */ 


LONG GpiPolyLine (HPS hps, LONG ICount, PPOINTL aptIPoInts) 


This function draws a series of straight lines starting at the current position and connecting the 
points specified. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

ICount (LONG) - input 
Number of points 

Must not be negative. Zero is valid but causes no output. 

aptIPoInts (PPOINTL) - input 
Array of points. 


Returns 

Correlation and error indicators: 

GPI_OK Successful 

GPI_HITS Correlate hits 

GPI_ERROR Error. 

An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid length or count parameter was specified. 

An invalid coordinate value was specified. 

Nested figures have been detected within a path 
definition. 


Possible returns from WinGetLastError 

PMERRINVHPS 

PMERR_PS_BUSY 

PMERR_INV_LENGTH_OR_COUNT 

PMERRINVCOORDINATE 

PMERRINVNESTEDFIGURES 


Remarks 

On completion, current position is set to the last point. 

The maximum number of lines allowed in a polyline is device dependent, but is always greater than 
3 500 for GPIF_LONG format spaces and always greater than 7 200 for GPIF_SHORT format spaces 
(see the PS_FORMAT of GpiCreatePS for the meaning of this format). 
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GpiPolyLine 

Polyline 


Related Functions 

• GpiBox 

• GpiLine 

• GpiPolyLineDisjoint 

• GpiMove 

• GpiSetCurrentPosition 

• GpiSetLineEnd 

• GpiSetLineJoin 

• GpiSetLineType 

• GpiSetLineWidth 

• GpiSetLineWidthGeom 

• GpiPop 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiSetBackColor 

• GpiSetBackMix 

• GpiSetColor 

• GpiSetMix 

Graphic Elements and Orders 

Element Type: OCODE_GCLINE 

Note that GpiLine also generates this element type. 

Order: Line at Current Position 

As many of these orders are generated as is necessary to hold the specified points. 

Example Code 

This example uses the GpiPolyLine function to draw a triangle. 

Idefine INCL_GPIPRIMITIVES /* GPI primitive functions */ 
linclude <os2.h> 

HPS hps; /* presentation space handle */ 

POINTL ptl Triangle!] = { 100, 100, 200, 0, 0, 0 }; /* vertices */ 

GpiMove(hps, &ptl Triangle [2] ) ; /* moves to end point (0, 0)*/ 

GpiPolyLine(hps, 3L, &ptlTriangle[l]);/* draws triangle */ 
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GpiPolyLineDisjoint - 
Polyline Disjoint 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM. Also in COMMON section */ 


LONG GpiPolyLineDisjoint (HPS hps, LONG ICount, PPOINTL aptIPoInts) 


This function draws a series of disjoint straight lines using the end-point pairs specified. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

ICount (LONG) - input 
Number of points 

Must be even and not negative. Zero is valid, but it causes no output. The maximum number of 
points allowed is system-dependent, but it is at least 7 000. 

aptIPoInts (PPOINTL) - input 
Array of points. 


Returns 

Correlation/error indicator: 
GPI_OK Successful 

GPI_HITS Correlate hit(s) 

GPIERROR Error. 


Possible returns from WinGetLastError 

PMERRINVHPS 

PMERR_PS_BUSY 

PMERR_INV_LENGTH_OR_COUNT 

PMERRJNVCOORDINATE 

PMERRINVNESTEDFIGURES 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid length or count parameter was specified. 

An invalid coordinate value was specified. 

Nested figures have been detected within a path 
definition. 


Remarks 

The effect of this function is the same as the following sequence of calls: 


GpiMove (hps, Points[0]); 
GpiLine (hps, Points[l]); 
GpiMove (hps, Points[2]); 
GpiLine (hps, Points [3]); 


GpiMove (hps, Poi nts [Count-2] ) ; 
GpiLine (hps, Poi nts [Count-1]); 


On completion, current position is set to the last point. 
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GpiPolyLineDisjoint 
Polyline Disjoint 


Related Functions 

• GpiBox 

• GpiLine 

• GpiPolyLine 

• GpiMove 

• GpiSetCurrentPosition 

• GpiSetLineEnd 

• GpiSetLineJoin 

• GpiSetLineType 

• GpiSetLineWidth 

• GpiSetLineWidthGeom 

• GpiPop 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiSetBackColor 

• GpiSetBackMix 

• GpiSetColor 

• GpiSetMix 

Example Code 

This example uses the GpiPolyLineDisjoint function to draw two lines. 

Idefine INCL_GPIPRIMITIVES /* GPI primitive functions */ 

linclude <os2.h> 

HPS hps; /* presentation space handle 

POINTL ptl Lines [] = { 100, 100, 100, 200, /* line 1 */ 

200, 100, 200, 200 }; /* line 2 

GpiPolyLineDisjoint(hps, 4L, &ptl Li nes [1] ) ;/* draw lines */ 


*/ 

*/ 
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GpiPolyMarker - 
Polymarker 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


LONG GpiPolyMarker (HPS hps, LONG ICount, PPOINTL aptIPoInts) 


This function draws markers with their centers at each of a series of specified positions. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

ICount (LONG) - input 
Number of points. 

Must not be negative. Zero is valid but causes no output. 

aptIPoInts (PPOINTL) - input 
Array of points. 

A marker is drawn at each of these points. 

Returns 

Correlation and error indicators: 

GPI_OK Successful 

GPI_HITS Correlate hits 

GPI_ERROR Error. 

Possible returns from WinGetLastError 

PMERRJNVHPS 
PMERRPSBUSY 

PMERR_INV_LENGTH_OR_COUNT 
PMERRJNVCOORDINATE 

Remarks 

On completion, the current position is set to the position of the last marker in the series. The marker 
symbol is selected by the current values of the marker set and marker symbol attributes. 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid length or count parameter was specified. 

An invalid coordinate value was specified. 


Related Functions 

• GpiMarker 

• GpiSetMarker 

• GpiSetMarkerBox 

• GpiSetMarkerSet 

• GpiPop 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiSetBackColor 

• GpiSetBackMix 

• GpiSetColor 

• GpiSetMix 
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GpiPolyMarker 

Polymarker 


Graphic Elements and Orders 

Element Type: OCODE_GMRK 

Note that GpiMarker also generates this element type. 

Order: Marker at Given Position 

As many of these orders are generated as is necessary to hold the specified positions. 

Example Code 

This example uses the GpiPolyMarker function to draw a series of markers. It then uses the 
GpiPolyLine function to connect to markers with lines. 

Idefine INCL_GPI PRIMITIVES /* GPI primitive functions */ 
linclude <os2.h> 

HPS hps; /* presentation space handle */ 

POINTL ptlStart = { 0, 0 }; /* start point */ 

POINTL aptl [5] ={10, 8, 20, 17, 30, 28, 40, 51, 50, 46};/* points*/ 

GpiPolyMarker(hps, 51, aptl); 

GpiMove(hps, &ptlStart); 

GpiPolyLine(hps, 5L, aptl); 
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GpiPolySpline - 
Polyspline 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


LONG GpiPolySpline (HPS hps, LONG ICount, PPOINTL aptIPoInts) 


This function creates a succession of Bezier splines. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

ICount (LONG) - input 
Count of points. 

This is the number of points specified in aptIPoints. It must be three times the number of 
splines. The value must not be negative, and it must be divisible by 3. Zero is valid but causes 
no output. 

aptIPoints (PPOINTL) - input 
An array of points. 

The points are given in this order: 

ell, cl2, el, c21, c22, e2, ... csl, cs2, es 

where: 

csl is the first control point of spline s 
cs2 is the second control point of spline s 
es is the end point of spline s. 

Returns 

Correlation and error indicators: 

GPI_OK Successful 

GPI_HITS Correlate hits 

GPI_ERROR Error. 

Possible returns from WinGetLastError 

PMERRINVHPS 
PMERRPSBUSY 

PMERR_INV_LENGTH_OR_COUNT 
PMERRINVCOORDINATE 
PMERRJNVNESTEDFIGURES 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid length or count parameter was specified. 

An invalid coordinate value was specified. 

Nested figures have been detected within a path 
definition. 


Remarks 

The first B6zier spline starts from the current position and goes to the third specified point, with the 
first and second points used as control points. Subsequent splines start from the ending point of the 
previous spline, and end at the next specified point but two, with the intervening points their first and 
second control points. It is the responsibility of the application to ensure that the gradient is 
continuous at each end and start point, if this is required. 
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GpiPolySpline 

Polyspline 


On completion, the current position is set to the last specified point. Each individual spline always 
lies within the area bounded by the start, end, and control points. 

It is not an error for any of the points to be coincident. 

The maximum number of splines allowed is more than 2 500. 


Related Functions 

• GpiPointArc 

• GpiPolyFillet 

• GpiPolyFilletSharp 

• GpiSetArcParams 

• GpiSetDefArcParams 

• GpiSetLineType 

• GpiSetLineWidth 

• GpiPop 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiSetBackColor 

• GpiSetBackMix 

• GpiSetColor 

• GpiSetMix 

Graphic Elements and Orders 

Element Type: OCODE_GCBEZ 
Order: Bezier Spline at Current Position 

As many of these orders are generated as is necessary to hold the specified splines. 

Example Code 

This example uses the GpiPolySpline function to draw a curve. The curve is drawn within a skewed 
rectangle, with the bottom corners being the start and end points and the top corners being the 
control points. 


Idefine INCL_GPIPRIMITIVES /* GPI primitive functions */ 
linclude <os2.h> 

HPS hps; /* presentation space handle */ 

POINTL ptl Start = { 0, 0 }; /* start point */ 

POINTL aptl [3] = {0, 100, 200, 150, 200, 50 }; /* point array */ 

GpiMove(hps, &ptlStart); /* moves to start point */ 

GpiPolySpline(hps, /* presentation-space handle */ 

3L, /* 3 points in the array */ 

aptl); /* address of array of points */ 


5-216 PM Programming Reference 


GpiPop - 
Pop 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiPop (HPS hps, LONG ICount) 


This function restores the primitive attributes that have been saved on the stack. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

ICount (LONG) - input 

Number of attributes to be restored. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 


PMERRINVHPS 

PMERR_PS_BUSY 

PMERRINVMICROPSFUNCTION 

PMERR_INV_LENGTH_OR_COUNT 

PMERR_SEG_CALL_STACK_EMPTY 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An attempt was made to issue a function that is invalid in 
a micro presentation space. 

An invalid length or count parameter was specified. 

A call stack empty condition was detected when 
attempting a pop function during GpiPop or segment 
drawing. 


Remarks 

Each time a primitive attribute call (such as color, or line type) is issued and the attribute mode is set 
to AM_PRESERVE, the values are put into a “Last in, First out” stack. 

This function can reset the current attribute values (starting with the last one set) to the previous 
value; this is known as “popping.” This allows a called segment to change the values of the 
attributes, and allows them to be restored on return to the caller (an implicit GpiPop function is 
performed for each preserved attribute when returning from a called segment). 

When inside an area or path definition, this function is only valid if the attribute being popped is valid 
inside an area or path definition. 

Note: It is not possible to check whether the attribute to be popped is valid before issuing this 
function. 
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GpiPop 

Pop 


Related Functions 

• GpiQueryAttrMode 

• GpiQueryAttrs 

• GpiQueryDefAttrs 

• GpiRestorePS 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiRestorePS 

Graphic Elements and Orders 

Element Type: OCODE_GPOP 
Order: Pop 

ICount of these orders are generated. 

Example Code 

This example uses the GpiPop function to restore the fill pattern and color attribute after painting 
region. 


Idefine INCL_GPIPRIMITIVES /* GPI primitive functions */ 
Idefine INCL_GPIREGIONS /* GPI region functions */ 
linclude <os2.h> 

HPS hps; /* presentation space handle */ 
HRGN hrgn; /* region handle */ 


/* preserves attributes on stack */ 
GpiSetAttrMode (hps, AM_PRESERVE) ; 


GpiSetColor(hps, CLR_RED); /* sets color to red */ 
GpiSetPattern(hps, PATSYM_DIAG1) ; /* sets pattern to a diagonal */ 
GpiPaintRegion(hps, hrgn); 

GpiPop(hps, 2L); /* restores values of last two attributes set */ 
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GpiPtlnRegion - 
Point In Region 


#define INCL_GPIREGIONS /* Or use INCL_GPI or INCL_PM */ 


LONG GpiPtlnRegion (HPS hps, HRGN hrgn, PPOINTL pptIPoInt) 


This function checks whether a point lies within a region. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

The region must be owned by the device identified by the currently associated device context. 

hrgn (HRGN) - input 
Region handle. 

pptIPoInt (PPOINTL) - input 
Point to be checked. 

The point is in device coordinates. 

Returns 

Inside and error indicators: 

PRGN_OUTSIDE Not in region 
PRGNJNSIDE In region 
PRGN_ERROR Error. 

Possible returns from WinGetLastError 

PMERRINVHPS 
PMERRPSBUSY 

PMERRINVHRGN 
PMERRINVCOORDINATE 
PMERRREGIONISCLIPREGION 

PMERRHRGNBUSY 


An invalid presentation-space handle was specified 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid region handle was specified. 

An invalid coordinate value was specified. 

An attempt was made to perform a region operation on a 
region that is selected as a clip region. 

An internal region busy error was detected. The region 
was locked by one thread during an attempt to access it 
from another thread. 


Remarks 

It is invalid if the specified region is currently selected as the clip region (by GpiSetClipRegion). 
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GpiPtlnRegion 
Point In Region 


Related Functions 

• GpiCombineRegion 

• GpiCreateRegion 

• GpiDestroyRegion 

• GpiEqualRegion 

• GpiOffsetRegion 

• GpiPaintRegion 

• GpiQueryRegionBox 

• GpiQueryRegionRects 

• GpiRectlnRegion 

• GpiSetRegion 

Example Code 

This example uses GpiPtlnRegion to determine if the point (150,150) lies within a region. 


Idefine INCL_GPIREGIONS /* Region functions */ 
linclude <os2.h> 

LONG 1 Inside; /* inside/error indicator */ 
HPS hps; /* Presentation-space handle */ 
HRGN hrgn; /* handle for region */ 
POINTL pptl Point = {150L.150L};/* point to be checked */ 


RECTL arcl [3] = { 100, 100, 200, 200, /* 1st rectangle */ 

150, 150, 250, 250, /* 2nd rectangle */ 

200, 200, 300, 300 }; /* 3rd rectangle */ 

/* create a region comprising three rectangles */ 
hrgn = GpiCreateRegion(hps, 3L, arcl); 

llnside = GpiPtInRegion(hps, hrgn, &ppt 1 Point) ; 
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GpiPtVisible - 
Point Visible 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


LONG GpiPtVisible (HPS hps, PPOINTL pptlPolnl) 


This function checks whether a point is visible within the clipping region of the device associated 
with the specified presentation space. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

pptIPoInt (PPOINTL) - input 
Point to be checked. 

The point is given in world coordinates. 


Returns 

Visibility indicator: 

PVISJNVISIBLE Not visible 
PVIS_VISIBLE Visible 

PVIS_ERROR Error. 

Possible returns from WinGetLastError 

PMERR INV HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_COORDINATE An invalid coordinate value was specified. 

Remarks 

For the purposes of this function, the clipping region is defined as the intersection between the 
application clipping region, and any other clipping, including windowing. 


Related Functions 

• GpiExcludeClipRectangle 

• GpilntersectClipRectangle 

• GpiOffsetClipRegion 

• GpiQueryClipBox 

• GpiQueryClipRegion 

• GpiQueryPel 

• GpiRectVisible 

• GpiSetClipRegion 

• GpiSetGraphicsField 

• WinExcludellpdateRegion 
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GpiPtVisible - 
Point Visible 

Example Code 

This example uses GpiPtVisible to check whether (150,150) is visible within the clipping region of the 
device associated with the presentation space. 


Idefine INCL_GPI PRIMITIVES /* Primitive functions */ 
linclude <os2.h> 

LONG lVisibility; /‘visibility indicator */ 
HPS hps; /* Presentation-space handle */ 
POINTL pptl Point = {15OL.150L};/* point to be checked */ 


lVisibility = Gpi PtVi s i bl e(hps , &pptlPoint); 
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GpiPutData - 
Put Data 


#define INCL_GPISEGMENTS /* Or use INCL_GPI or INCL_PM */ 


LONG GpiPutData (HPS hps, LONG IFormat, PLONG pILength, PBYTE pbData) 


This function passes a buffer of graphics orders to the current segment, or draws the orders, or both 
of these. For details of the orders, see Chapter 33, “Graphics Orders.” 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

IFormat (LONG) - input 
Coordinate type used: 


DFORM_NOCONV 

DFORMS370SHORT 

DFORMPCSHORT 

DFORMPCLONG 


No coordinate conversion performed 
S/370 format short (2-byte) integers 
PC format short (2-byte) integers 
PC format long (4-byte) integers. 


pILength (PLONG) - input/output 
Length of graphic data. 


Set by the application to the length of order data in pbData. If an incomplete order occurred, it is 
updated, on return, to the offset of the start of the incomplete order. 


pILength must not be greater than 63 KB. 

pbData (PBYTE) - input 
Orders to be copied. 


Returns 

Correlation and error indicators: 
GPI_OK Successful 

GPI_HITS Correlate hits 

GPIJERROR Error. 


Possible returns from WinGetLastError 


PMERRINVHPS 

PMERRPSBUSY 

P M E R R_IN V_PUTDAT A_FOR M AT 

PMERR_INV_LENGTH_OR_COUNT 

PMERRINVMICROPSFUNCTION 

P M E R R_DAT A_T OOLONG 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid format parameter was specified with 
GpiPutData. 

An invalid length or count parameter was specified. 

An attempt was made to issue a function that is invalid in 
a micro presentation space. 

An attempt was made to transfer more than the maximum 
permitted amount of data (64512 bytes) using GpiPutData, 
GpiGetData, or GpiElement. 
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GpiPutData 
Put Data 


PMERR_INV_ELEMENT_POINTER An attempt was made to issue GpiPutData with the 

element pointer not pointing at the last element. 

PMERR_INV_REPLACE_MODE_FUNC An attempt was made to issue GpiPutData with the editing 

mode set to SEGEM_REPLACE. 

PMERRORDERTOOBIG An internal size limit was exceeded while converting 

orders from short to long format during GpiPutData 
processing. An order was too long to convert. 


Remarks 

The orders passed may be added to the current segment, drawn immediately, or both, depending on 
the current drawing mode (see GpiSetDrawingMode), and whether the primitives are within a 
segment. 

If there is an incomplete order at the end of the buffer, pi Length is updated to point to the start of the 
incomplete order. The application can then concatenate this partial order in front of the next buffer. 

The orders End Prolog and Set Viewing Transform are not allowed. 

This function is valid within an element bracket (see GpiBeginElement). It can contain 
GpiBeginElement and GpiEndElement orders, while these are in the correct sequence with respect to 
the currently opened segment in segment store. 

The data in the buffer is converted, if necessary, to the presentation space format (defined when the 
presentation space is first created; see GpiCreatePS). 

This function is invalid if the editing mode (see GpiSetEditMode) is set to SEGEMREPLACE, and also 
in SEGEMJNSERT mode if the element pointer is not pointing to the last element. 


Related Functions 

• GpiBeginElement 

• GpiEndElement 

• GpiGetData 
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GpiPutData - 
Put Data 


Example Code 

This example uses the GpiPutData function to copy graphics orders from one segment to another. 


Idefine INCL_GPISEGMENTS /* Segment functions */ 
finclude <os2.h> 

HPS hps; /* presentation space handle */ 
LONG f Format = DFORMNOCONV;/* do not convert coordinates */ 
LONG offSegment = 0L; /* offset in segment */ 
LONG offNextElement =0;/* offset in segment to next element */ 
LONG cb = 0L; /* bytes retrieved */ 
BYTE abBuffer[512] ; /* data buffer */ 


GpiOpenSegment(hps, 3L); /* open segment to receive the data */ 

do { 

offSegment += cb; 
offNextElement = offSegment; 

cb = GpiGetData(hps, 2L, HoffNextElement, fFormat, 512L, abBuffer); 


/* Put data in other segment. */ 


if (cb > 0L) GpiPutData (hps, /* presentation-space handle 


fFormat, 

&cb, 

abBuffer) ; 


/* format of coordinates * 
/* number of bytes in buffer * 
buffer with graphics-order data * 


/ 

/ 

/ 

/ 


} while (cb > 0L) ; 

GpiCloseSegment(hps) ; /* close segment that received data */ 
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GpiQueryArcParams - 
Query Arc Parameters 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiQueryArcParams (HPS hps, PARCPARAMS parcpArcParams) 


This function returns the current arc parameters used to draw full, partial, and 3-point arcs. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

parcpArcParams (PARCPARAMS) - output 
Arc parameters. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 

PMERR INV HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_IN_RETAIN_MODE An attempt was made to issue a function (for example, 

query) that is invalid when the actual drawing mode is not 

draw or draw-and-retaln. 

PMERRJNV_DC_TYPE An invalid type parameter was specified with 

DevOpenDC, or a function was issued that is invalid for a 
OD_METAFILE_NOQUERY device context. 


Remarks 

Arc parameters are set by GpiSetArcParams. 

This function is invalid when the drawing mode (see GpiSetDrawingMode) is set to retain. 


Related Functions 

• GpiQueryAttrs 

• GpiSetArcParams 
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GpiQueryArcParams - 
Query Arc Parameters 


Example Code 

This example uses GpiQueryArcParams to return the current arc parameters used to draw full, 
partial, and 3-point arcs. The example queries the arc parameters and assigns a variable to the P 
coefficient if the query succeeds. 


Idefine INCL_GPIPRIMITIVES /* Primitive functions */ 
linclude <os2.h> 

BOOL f Success; /* success indicator */ 
HPS hps; /* Presentation-space handle */ 
ARCPARAMS parcpArcParams; /* Arc parameters */ 
LONG lPcoefficient; /* p coefficient of arc definition */ 


f Success = GpiQueryArcParams (hps, &parcpArcParams) ; 

/* if successful, assign value of P coefficient */ 
if (fSuccess == TRUE) 

lPcoefficient = parcpArcParams. IP; 
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GpiQueryAttrMode - 
Query Attribute Mode 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


LONG GpiQueryAttrMode (HPS hps) 


This function returns the current value of the attribute mode, as set by GpiSetAttrMode. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 


Returns 

Current attribute mode: 

>0 Current attribute mode 

AM_ERROR Error. 

Possible returns from WinGetLastError 

PMERR_INV_HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 


Related Functions 

• GpiQueryAttrs 

• GpiSetAttrMode 

Example Code 

This example uses GpiQueryAttrMode to return the current value of the attribute mode and sets a 
new mode using GpiSetAttrMode; after the application has finished using the new mode, the original 
attribute mode is restored. 

Idefine INCL_GPI PRIMITIVES /* Primitive functions */ 

linclude <os2.h> 

LONG IMode; /* current attribute mode (or error) */ 

HPS hps; /* Presentation-space handle */ 

/* query current attribute mode */ 

IMode = GpiQueryAttrMode (hps) ; 

/* set new mode */ 

Gpi Set AttrMode(hps , AM_PRESERVE) ; 


/* restore original mode */ 
GpiSetAttrMode (hps, IMode); 
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GpiQueryAttrs - 
Query Attributes 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


LONG GpiQueryAttrs (HPS hps, LONG IPrlmType, ULONG flAttrMask, PBUNDLE ppbunAttrs) 


This function returns current attributes for the specified primitive type. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

IPrlmType (LONG) - input 
Primitive type. 


This is the type of 

PRIMJJNE 
PRIMCHAR 
PRIMMARKER 
PRIMAREA 
PRIMIMAGE 
flAttrMask (ULONG) - 


primitive for which attributes are to be queried, as follows: 

Line and arc primitives 

Character primitives 

Marker primitives 

Area primitives 

Image primitives. 

input 


Attributes mask. 


Each flag that is set indicates that the corresponding flag in IDefMask is to be updated, and that if 
the corresponding attribute is not currently set to default, its value is to be returned in the 
ppbunAttrs buffer. 

If all flags in flAttrMask are zero, the ppbunAttrs buffer address is not used. 

ppbunAttrs (PBUNDLE) - output 
Attributes. 

ppbunAttrs is a buffer in which is returned the value of each non-default attribute for which the 
flAttrMask flag is set, in the order specified in GpiSetAttrs for the particular primitive type. 

Only data for attributes for which the appropriate flag in flAttrMask is set is updated, so 
ppbunAttrs need only be large enough for the highest offset attribute to be returned (see 
GpiSetAttrs). 

The data returned in ppbunAttrs for any attribute for which the flAttrMask flag is set, but which is 
currently set to default, is undefined. 


Returns 

Defaults mask. 

As f IDefMask in GpiSetAttrs: 

GPI_ALTERROR Error occurred 

Positive Defaults mask, numeric value can be greater than or equal to 0. 

Possible returns from WinGetLastError 

PMERRJNV HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 
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GpiQueryAttrs - 
Query Attributes 


PMERR_INV_PRIMmVE_TYPE 

PMERRUNSUPPORTEDATTR 

PMERRINVINRET AINMODE 


PMERR_INV_DC_TYPE 


An invalid primitive type parameter was specified with 
GpiSetAttrs or GpiQueryAttrs. 

An unsupported attribute was specified in the attrmask 
with GpiSetAttrs or GpiQueryAttrs. 

An attempt was made to issue a function (for example, 
query) that is invalid when the actual drawing mode is not 

draw or draw-and-retaln. 

An invalid type parameter was specified with 
DevOpenDC, or a function was issued that is invalid for a 
OD_METAFILE_NOQUERY device context. 


Remarks 

This function is invalid when the drawing mode (see GpiSetDrawingMode) is set to retain. This 
function returns a mask, similar in meaning to fIDefMask in GpiSetAttrs. Each flag in the returned 
mask is updated if the corresponding flag in flAttrMask is set. It is set if the attribute is set to the 
default, otherwise it is reset. Other flags are undefined. 

The parameters returned by this function may be used to reinstate exactly the same attributes as are 
queried, using GpiSetAttrs. 


Related Functions 

• GpiSetAttrs 


Example Code 

This example uses the GpiQueryAttrs function to retrieve the current attributes for the line primitive. 

Idefine INCL_GPIPRIMITIVES /* GPI primitive functions */ 
linclude <os2.h> 

HPS hps; /* presentation space handle */ 

LINEBUNDLE lbnd; 

LONG fIDefMask; 

fIDefMask = GpiQueryAttrs (hps, 

PRIM LINE, 

LBB_C0L0R | 

LBB_MIX_MODE | 

LBB_WIDTH | 

LBB GEOM WIDTH | 

LBB_TYPE | 

LBB_END | 

LBB_J0IN, 

&1 bnd) ; 

if (fIDefMask & LBB_C0L0R) 

{ 

/* The line color has the default value. */ 

} 


/* presentation-space handle */ 


/* line primitive */ 
/* line color */ 
/* color-mix mode */ 
/* line width */ 
/* geometric-line width */ 
/* line style */ 
/* line-end style */ 
/* line-join style */ 
/* buffer for attributes */ 
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GpiQueryBackColor - 
Query Background Color 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


LONG GpiQueryBackColor (HPS hps) 


This function returns the current value of the (character) background color attribute, as set by the 
GpiSetBackColor function. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 


Returns 

Background color: 

CLR_ERROR Error 

CLR_DEFAULT Default 

Otherwise Background color index. 

Possible returns from WinGetLastError 

PMERR_INV_HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_IN_RETAIN_MODE An attempt was made to issue a function (for example, 

query) that is invalid when the actual drawing mode is not 

draw or draw-and-retaln. 

PMERRJNV_DC_TYPE An invalid type parameter was specified with 

DevOpenDC, or a function was issued that is invalid for a 
OD_METAFILE_NOQUERY device context. 


Remarks 

This function is invalid when the drawing mode (see GpiSetDrawingMode) is set to retain. 


Related Functions 

• GpiQueryAttrs 

• GpiSetBackColor 

Example Code 

This example uses GpiQueryBackColor to return the current value of the (character) background 
color attribute, as set by the GpiSetBackColor call. 

Idefine INCL_GPI PRIMITIVES /* Primitive functions */ 

linclude <os2.h> 

LONG 1 Col or; /* current background color (or error) */ 

HPS hps; /* Presentation-space handle */ 

IColor = GpiQueryBackColor(hps) ; 
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GpiQueryBackMix - 
Query Background Mix 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


LONG GpiQueryBackMix (HPS hps) 


This function returns the current value of the (character) background color-mixing mode, as set by 
the GpiSetBackMix function. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 


Returns 

Background mix: 

BM_DEFAULT Default 
>0 Background mix mode 

BM_ERROR Error. 

Possible returns from WinGetLastError 

PMERR_INV_HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_IN_RETAIN_MODE An attempt was made to issue a function (for example, 

query) that is invalid when the actual drawing mode is not 

draw or draw-and-retaln. 

PMERR_INV_DC_TYPE An invalid type parameter was specified with 

DevOpenDC, or a function was issued that is invalid for a 
OD_METAFILE_NOQUERY device context. 


Remarks 

This function is invalid when the drawing mode (see GpiSetDrawingMode) is set to retain. 


Related Functions 

• GpiQueryAttrs 

* GpiSetBackMix 

Example Code 

This example uses GpiQueryBackMix to return the current value of the (character) background 
color-mixing mode, as set by the GpiSetBackMix call. 

Idefine INCL_GPIPRIMITIVES /* Primitive functions */ 

linclude <os2.h> 

LONG lMixMode; /* current background mix (or error) */ 

HPS hps; /* Presentation-space handle */ 

lMixMode = GpiQueryBackMix(hps) ; 
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GpiQueryBitmapBits - 
Query Bit-Map Bits 


#define INCL_GPIBITMAPS /* Or use INCL_GPI or INCL_PM */ 


LONG GpiQueryBitmapBits (HPS hps, LONG IScanStart, LONG IScans, PBYTE pbBuffer, 

PBITMAPINF02 pbml2lnfoTable) 


This function transfers data from a bit map to application storage. 

Parameters 

bps (HPS) - input 

Presentation-space handle. 

IScanStart (LONG) - input 
Starting line number. 

Scan-line number at which the data transfer is to start, counting from zero as the bottom line. 

IScans (LONG) - input 

Number of scan lines to be returned. 

pbBuffer (PBYTE) - output 
Data area. 

Data area into which the bit-map data is copied. 

pbml2lnfoTable (PBITMAPINF02) - input/output 
Bit-map information table. 

Storage must be provided for the associated color table. 

Returns 

Number of scan lines actually returned: 

>0 Number of scan lines actually returned 

GPI_ALTERROR Error. 

Possible returns from WinGetLastError 

PMERRINVHPS 
PMERRPSBUSY 

PMERR_INV_LENGTH_OR_COUNT 
PMERRINVJNFOTABLE 

PMERRNOBITMAPSELECTED 

PMERR_INV_SCAN_START 

PMERR_INCORRECT_DC_TYPE 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid length or count parameter was specified. 

An invalid bit-map info table was specified with a bit-map 
operation. 

An attempt has been made to operate on a memory 
device context that has no bit map selected. 

An invalid scanstart parameter was specified with a 
bitmap function. 

An attempt was made to perform a bit-map operation on a 
presentation space associated with a device context of a 
type that is unable to support bit-map operations. 
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Query Bit-Map Bits 


Remarks 

The presentation space must be currently associated with a memory device context, which has a bit 
map currently selected. 

The pbmi2lnfoTable must be initialized by the application with the values of cbFix, and also cPIanes 
and cBitCount, set to the format required. The standard bit-map formats are supported, plus any 
known to be supported by the device (see GpiQueryDeviceBitmapFormats). Each of the following 
fields must also be set by the application before issuing the call (unless the BITMAPINF02 structure 
is truncated and the field is not present): 

• ulCompression 

• usReserved 

• usRecording 

• usRendering 

• ulColorEncoding 

This function returns the values of cx, cy (plus any other information, apart from that set by the 
application, for which space is available in the BITMAPINF02 structure), and the color table array 
filled in by the system. 

The bit-map data is converted where necessary. 

pbBuffer must point to a storage area large enough to contain data for the requested number of scan 
lines. The amount of storage required for one scan line can be determined by 
GpiQueryBitmapParameters. It is 

((bitcount*bitmapwidth + 31)/32)*planes*4 bytes 

The storage required for the entire bit map is this value multiplied by bltmaphelght. 

Related Functions 

• GpiSetBitmapBits 
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Query Bit-Map Bits 


Example Code 

This example uses GpiQueryBitmapBits to copy the image data of a bit map from a presentation 
space associated with a memory device context. 


Idefine INCL_GPIBITMAPS /* GPI Bit-map functions */ 
Idefine INCL_DOSMEMMGR /* DOS Memory Manager Functions */ 
linclude <os2.h> 

HPS hps; /* presentation space handle */ 
BITMAPINF0HEADER2 bmp = { 16, 640, 350, 1, 1 }; /* info struct */ 
ULONG cbBuffer, cbBitmapInfo; /* buffer lengths */ 
PBYTE pbBuffer; /* bit-map data buffer */ 
PBITMAPINF02 pbmi; /* info structure */ 


/* 

* Compute the size of the image-data buffer and the bit map 

* information structure. 

*/ 

cbBuffer = (((bmp.cBitCount * bmp.cx) + 31) / 32) 

* 4 * bmp.cy * bmp.cPlanes; 
cbBitmapInfo = sizeof(BITMAPINF02) + 

(sizeof(RGB) * (1 « bmp.cBitCount)); 


/* 

* Allocate memory for the image data-buffer and the bit map 

* information structure. 

*/ 

DosAllocMem((VOID *) pbBuffer, cbBuffer, 

PAG_COMMIT | PAG_READ | PAG_WRITE) ; 
DosAllocMem((VOID *) pbmi .cbBitmapInfo, 

PAG_COMMIT | PAG_READ | PAG_WRITE) ; 

/* Copy the image data. */ 
pbmi->cbFix = 16L; 
pbmi->cPlanes = 1; 
pbmi->cBitCount = 1; 

GpiQueryBitmapBits (hps, 0L, (LONG) bmp.cy, pbBuffer, pbmi); 
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Query Bit-Map Dimension 


#define INCL_GPIBITMAPS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiQueryBitmapDimension (HBITMAP hbm, PSIZEL psIzIBItmapDImenslon) 


This function returns the width and height of a bit map, as specified on a previous 
GpiSetBitmapDimension function. 


Parameters 

hbm (HBITMAP) - input 
Bit-map handle. 

psIzIBItmapDImenslon (PSIZEL) - output 
Size of bit map. 

The width and height of the bit map in 0.1 millimeter units. 
If not set by GpiSetBitmapDimension, zeros are returned. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERR INV HBITMAP An invalid bit-map handle was specified. 

PMERR_HBITMAP_BUSY An internal bit map busy error was detected. The bit map 

was locked by one thread during an attempt to access it 
from another thread. 

Related Functions 

• GpiSetBitmapDimension 

Example Code 

This example uses GpiQueryBitmapDimension to return the width and height of a bit map, as 
specified on a previous GpiSetBitmapDimension call; if successful, it assigns the width to a variable. 


Idefine INCL_GPIBITMAPS /* Bit-map functions */ 
linclude <os2.h> 

BOOL f Success; /* success indicator */ 
HBITMAP hbm; /* bit-map handle */ 
SIZEL psizlBitmapDimension; /* size of bit map */ 
LONG lWidth; /* width of bit map */ 


fSuccess = GpiQueryBitmapDimension(hbm, &psizlBitmapDimension); 

/* if successful, assign value of bit-map width */ 
if (fSuccess == TRUE) 

lWidth = psizlBitmapDimension. cx; 
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GpiQueryBitmapInfoHeader - 
Query Bit-Map Info Header 


#define INCL_GPIBITMAPS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiQueryBitmapInfoHeader (HBITMAP hbm, PBITMAPINFOHEADER2 pbmp2Data) 


This function returns information about a bit map identified by the bit-map handle. 


Parameters 

hbm (HBITMAP) - input 
Bit-map handle. 

pbmp2Data (PBITMAPINFOHEADER2) - input/output 
Bit-map information header. 

This is a structure, that on return, is filled with data for the specified bit map. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERR INV HBITMAP An invalid bit-map handle was specified. 

PMERR_HBITMAP_BUSY An internal bit map busy error was detected. The bit map 

was locked by one thread during an attempt to access it 
from another thread. 


Remarks 

The cbFix field of the BITMAPINFOHEADER2 structure must be set by the application before 
performing this function. 

Note: This function should be used in preference to the GpiQueryBitmapParameters function. 
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GpiQueryBitmapInfoHeader 
Query Bit-Map Info Header 


Example Code 

This example uses GpiQueryBitmapInfoHeader to return information about a bit map identified by 
the bit-map handle; if successful, it uses this information to create a new bit map via 
GpiCreateBitmap. 


Idefine INCL_GPIBITMAPS /* Bit-map functions */ 

linclude <os2.h> 

HPS hps; /* presentation-space handle */ 

BOOL f Success; /* success indicator */ 

HBITMAP hbm; /* bit-map handle */ 

HBITMAP hbmNew; /* bit-map handle */ 

BITMAPINF0HEADER2 pbmp2Data; /* Bit-map information header */ 
PBYTE pb; /* address of bit-map image data in 

resource */ 


/* set size of info structure */ 
pbmp2Data.cbFix = 16L; 

fSuccess = GpiQueryBitmapInfoHeader(hbm, &pbmp2Data); 


/* use information to create bit map */ 

hbmNew = GpiCreateBitmap (hps, /* presentation space 

&pbmp2Data, /* bit-map information header 

CBM_INIT, /* initialize the bit map 

pb, /* bit-map data 

(PBITMAPINF02)&pbmp2Data) ; 

/* bit-map information table 


*/ 

*/ 

*/ 
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Query Bit-Map Handle 


#define INCL_GPIBITMAPS /* Or use INCL_GPI or INCL_PM */ 


HBITMAP GpiQueryBitmapHandle (HPS hps, LONG ILcId) 


This function returns the handle of the bit map currently tagged with the specified local identifier 
(Icid). 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

ILcId (LONG) - input 
Local identifier. 


Returns 

Bit-map handle: 

^0 Bit-map handle 

GPI_ERROR Error. 

Possible returns from WinGetLastError 

PMERRJNV HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_SETID An invalid setid parameter was specified. 

PMERR_ID_HAS_NO_BITMAP No bit map was tagged with the setid specified on a 

GpiQueryBitmapHandle call. 

Remarks 

An error is raised if a bit map is not currently tagged with the specified Icid. 

Related Functions 

• GpiSetBitmapid 

Example Code 

This example uses GpiQueryBitmapHandle to return the handle of the bit map currently tagged with 
the specified local identifier (Icid) set by GpiSetBitmapid. 

Idefine INCL_GPIBITMAPS /* Bit-map functions */ 

linclude <os2.h> 

HBITMAP hbm; /* bit-map handle */ 

HPS hps; /* presentation-space handle */ 

LONG ILcid; /* local identifier */ 

hbm = GpiQueryBitmapHandle (hps, ILcid); 
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GpiQueryBitmapParameters 
Query Bit-Map Parameters 


^define INCL_GPIBITMAPS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiQueryBitmapParameters (HBITMAP hbm, PBITMAPINFOHEADER pbmpData) 


This function returns information about a bit map identified by the bit-map handle. 


Parameters 

hbm (HBITMAP) - input 
Bit-map handle. 

pbmpData (PBITMAPINFOHEADER) - input/output 
Bit-map information header. 

This is a structure, that on return, is filled with data for the specified bit map. The structure 
includes the elements (width, height, planes, bitcount) of a bit-map information table. 

Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 

PMERR INV HBITMAP An invalid bit-map handle was specified. 

PMERR_HBITMAP_BUSY An internal bit map busy error was detected. The bit map 

was locked by one thread during an attempt to access it 
from another thread. 


Remarks 

The cbFix field of the BITMAPINFOHEADER structure must be set by the application before 
performing this function. 


Related Functions 

• GpiCreateBitmap 
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GpiQueryBitmapParameters - 
Query Bit-Map Parameters 


Example Code 

This example uses GpiQueryBitmapParameters to return information about a bit map identified by 
the bit-map handle; if successful, it assigns the width field to a variable. 


Idefine INCL_GPIBITMAPS /* Bit-map functions */ 

linclude <os2.h> 

BOOL fSuccess; /* success indicator */ 

HBITMAP hbm; /* bit-map handle */ 

BITMAPINFOHEADER pbmpData; /* bit-map information header */ 
USHORT usWidth; /* width of bit map */ 


/* set size of info structure */ 
pbmpData. cbFix = si zeof (BITMAPINFOHEADER) ; 

fSuccess = GpiQueryBitmapParameters(hbm, &pbmpData); 

/* if successful, assign value of bit-map width */ 
if (fSuccess == TRUE) 
usWidth = pbmpData. cx; 


Chapter 5. Graphics Functions 5-241 



GpiQueryBoundaryData 
Query Boundary Data 


#define INCL_GPICORRELATION /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiQueryBoundaryData (HPS hps, PRECTL prcIBoundary) 


This function returns the boundary data. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

prcIBoundary (PRECTL) - output 
Boundary data. 

A rectangle structure in which the boundary data is returned, containing the following fields: 

xmin Lowest x value found 

ymin Lowest y value found 

xmax Highest x value found 

ymax Highest y value found. 

Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERR INV HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_COORDINATE_OVERFLOW An internal coordinate overflow error occurred. This can 

occur if coordinates or matrix transformation elements (or 
both) are invalid or too large. 

PMERR_INV_DC_TYPE An invalid type parameter was specified with 

DevOpenDC, or a function was issued that is invalid for a 
OD_METAFILE_NOQUERY device context. 


Remarks 

This function returns the boundary data set upon completion of the last boundary calculation. 
Boundary data is returned as the coordinates in model space. 

Boundary data is inclusive. A null boundary is indicated if xmin is greater than xmax, or if ymin is 
greater than ymax. After GpiResetBoundaryData, xmin and ymin are the maximum positive 
numbers, and xmax and ymax are the maximum negative numbers. 
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GpiQueryBoundaryData - 
Query Boundary Data 


Related Functions 

• GpiResetBoundaryData 

• GpiSetDrawControl 

Example Code 

This example uses the GpiQueryBoundaryData function to retrieve the rectangle enclosing the 
output. The boundary data is then used to draw a border around the output. 


fdefine INCL_GPICORRELATION 

fdefine INCL_GPIPRIMITIVES /* GPI primitive functions */ 

fdefine INCL_GPICONTROL /* GPI control Functions */ 

finclude <os2.h> 

HPS hps; /* presentation space handle */ 

POINTL ptlStart = { 0, 0 }; /* first vertex */ 

POINTL ptlTriangle[] = { 100, 100, 200, 0, 0, 0 }; /* vertices */ 
RECTL rcl ; /* rectangle */ 

GpiSetDrawControl (hps, 

DCTL_B0UNDARY , DCTL_0N); /* accumulate boundary data */ 

GpiMove(hps, SptlStart); /* produce output */ 

GpiPolyLine(hps, 3L, ptlTriangle) ; 

GpiQueryBoundaryData (hps, &rcl); /* copy boundary data to rcl */ 

if (rcl.xLeft < rcl.xRight) { /* verify output exists*/ 

ptlStart. x = rcl.xLeft; ptlStart. y = rcl.yBottom; 


GpiMove(hps, &ptlStart); /* move to lower-right corner */ 
ptlStart. x = rcl.xRight; ptlStart. y = rcl.yTop; 

GpiBox(hps, DR00UTLINE, SptlStart, 0L, 0L); /* draw border */ 

} 
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GpiQueryCharAngle - 
Query Character Angle 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiQueryCharAngle (HPS hps, PGRADIENTL pgradlAngle) 


This function returns the current value of the character baseline angle. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

pgradlAngle (PGRADIENTL) - output 
Baseline angle. 

A point, relative to (0,0), that defines the character baseline angle vector. 

If the character angle is currently set to the default value, (0,0) is returned. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 

PMERR INV HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERRINVINRETAINMODE An attempt was made to issue a function (for example, 

query) that is invalid when the actual drawing mode is not 

draw or draw-and-retaln. 

PMERR INV DC_TYPE An invalid type parameter was specified with 

DevOpenDC, or a function was issued that is invalid for a 
OD_METAFILE_NOQUERY device context. 


Remarks 

This function is invalid when the drawing mode (see GpiSetDrawingMode) is set to retain. 


Related Functions 

• GpiQueryAttrs 

• GpiSetCharAngle 
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GpiQueryCharAngle - 
Query Character Angle 


Example Code 

This example uses GpiQueryCharAngle to return the current value of the character baseline angle; if 
successful, it places the x component in a variable. 


Idefine INCL_GPIPRIMITIVES /* Primitive functions */ 
linclude <os2.h> 

BOOL f Success; /* success indicator */ 
HPS hps; /* Presentation-space handle */ 
LONG lxComponent; /* x component of baseline angle */ 
GRADIENTL pgradl Angle; /* Baseline angle */ 


fSuccess = GpiQueryCharAngle (hps, &pgradlAngle) ; 

if (fSuccess == TRUE) 

lxComponent = pgradl Angle. x; 
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GpiQueryCharBox - 
Query Character Box 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM 7 


BOOL GpiQueryCharBox (HPS hps, PSIZEF psIzfxSIze) 


This function returns the current value of the character box attribute, as set by the GpiSetCharBox 
function. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

psIzfxSIze (PSIZEF) - output 
Character-box size. 

If the character box is currently set to the default, the default size is returned. This is the size 
returned by DevQueryCaps (CAPS_GRAPHICS_CHAR_WIDTH and 
CAPS_GRAPHICS_CHAR_HEIGHT), converted to presentation page space. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 

PMERR_INV_HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_IN_RETAIN_MODE An attempt was made to issue a function (for example, 

query) that is invalid when the actual drawing mode is not 

draw or draw-and-retaln. 

PMERR_INV_DC_TYPE An invalid type parameter was specified with 

DevOpenDC, or a function was issued that is invalid for a 
OD_METAFILE_NOQUERY device context. 


Remarks 

In general this function does not return the same box as GpiQueryTextBox for an average-sized 
character. For outline fonts the character-box attribute is mapped to a particular font dimension 
related to the point size, for raster fonts it does not correspond to any font metric. (See 
GpiSetCharMode). 

This function is invalid when the drawing mode (see GpiSetDrawingMode) is set to retain. 


Related Functions 

• DevQueryCaps 

• GpiQueryAttrs 

• GpiSetCharBox 


5-246 


PM Programming Reference 







GpiQueryCharBox - 
Query Character Box 


Example Code 

This example uses GpiQueryCharBox to return the current value of the character box attribute, as 
set by the GpiSetCharBox call; if successful, places the box width in a variable. 


Idefine INCL_GPIPRIMITIVES /* Primitive functions */ 
linclude <os2.h> 

BOOL f Success; /* success indicator */ 
HPS hps; /* Presentation-space handle */ 
SIZEF psizfxSize; /* Character-box size */ 
FIXED lWidth; /* character box width */ 


fSuccess = GpiQueryCharBox (hps, SpsizfxSize) ; 

if (fSuccess == TRUE) 
lWidth = psizfxSize.cx; 
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GpiQueryCharBreakExtra - 
Query Character Break Extra 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiQueryCharBreakExtra (HPS hps, PFIXED pfxBreakExtra) 


This function returns the current value of the character-break-extra attribute, as set by the 
GpiSetCharBreakExtra function. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

pfxBreakExtra (PFIXED) - output 

Character-break-extra attribute value. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 


PMERRINVHPS 

PMERRPSBUSY 

PMERRINVINRETAINMODE 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An attempt was made to issue a function (for example, 
query) that is invalid when the actual drawing mode is not 

draw or draw-and-retaln. 


Remarks 

This function is invalid when the drawing mode (see GpiSetDrawingMode) is set to retain. 

Example Code 

This example uses GpiQueryCharBreakExtra to return the current value of the character-break-extra 
attribute, as set by the GpiSetCharBreakExtra call. 

Idefine INCL_GPIPRIMITIVES /* Primitive functions */ 

linclude <os2.h> 

BOOL f Success; /* success indicator */ 

HPS hps; /* Presentation-space handle */ 

FIXED pfxBreakExtra; /* Character-break-extra attribute value*/ 

fSuccess = GpiQueryCharBreakExtra (hps, SpfxBreakExtra) ; 
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GpiQueryCharDirection - 
Query Character Direction 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


LONG GpiQueryCharDirection (HPS hps) 


This call returns the current value of the character direction attribute, as set by the 
GpiSetCharDirection function. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 


Returns 

Character direction: 


CHDIRN_DEFAULT Default 
>0 Character direction 


CHDIRN_ERROR Error. 


Possible returns from WinGetLastError 

PMERR_INV_HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_IN_RETAIN_MODE An attempt was made to issue a function (for example, 

query) that is invalid when the actual drawing mode is not 

draw or draw-and-retain. 

PMERR_INV_DC_TYPE An invalid type parameter was specified with 

DevOpenDC, or a function was issued that is invalid for a 
OD_METAFILE_NOQUERY device context. 


Remarks 

This call is invalid when the drawing mode (see GpiSetDrawingMode) is set to retain. 


Related Functions 

• GpiQueryAttrs 

• GpiSetCharDirection 

Example Code 

This example uses GpiQueryCharDirection to return the current value of the character direction 
attribute, as set by the GpiSetCharDirection call. 

Idefine INCL_GPIPRIMITIVES /* Primitive functions */ 

linclude <os2.h> 

LONG 1 Direct ion; /* character direction (or error) */ 

HPS hps; /* Presentation-space handle */ 

IDirection = GpiQueryCharDirection(hps); 
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GpiQueryCharExtra - 
Query Character Extra 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiQueryCharExtra (HPS hps, PFIXED pfxExtra) 


This function returns the current value of the character-extra attribute, as set by the GpiSetCharExtra 
function. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

pfxExtra (PFIXED) - output 

Character-extra attribute value. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An attempt was made to issue a function (for example, 
query) that is invalid when the actual drawing mode is not 

draw or draw-and-retaln. 


PMERRINVHPS 

PMERR_PS_BUSY 

PMERRINVJNRETAINMODE 


Remarks 

This function is invalid when the drawing mode (see GpiSetDrawingMode) is set to retain. 


Example Code 

This example uses GpiQueryCharExtra to return the current value of the character-extra attribute, 
as set by the GpiSetCharExtra call. 


Idefine INCL_GPIPRIMITIVES /* Primitive functions */ 
linclude <os2.h> 

BOOL f Success; /* success indicator */ 
HPS hps; /* Presentation-space handle */ 
FIXED pfxExtra; /* Character-extra attribute value. */ 


f Success = GpiQueryCharExtra (hps, SpfxExtra); 
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GpiQueryCharMode - 
Query Character Mode 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


LONG GpiQueryCharMode (HPS hps) 


This function returns the current value of the character-mode attribute, as set by the 
GpiSetCharMode function. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 


Returns 

Character mode: 


CM_DEFAULT 

>0 

CMERROR 


Default 

Character mode 
Error. 


Possible returns from WinGetLastError 

PMERR_INV_HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_IN_RETAIN_MODE An attempt was made to issue a function (for example, 

query) that is invalid when the actual drawing mode is not 

draw or draw-and-retaln. 

PMERR_INV_DC_TYPE An invalid type parameter was specified with 

DevOpenDC, or a function was issued that is invalid for a 
OD_METAFILE_NOQUERY device context. 


Remarks 

This function is invalid when the drawing mode (see GpiSetDrawingMode) is set to retain. 


Related Functions 

• GpiQueryAttrs 

• GpiSetCharMode 

Example Code 

This example uses GpiQueryCharMode to return the current value of the character mode attribute, 
as set by the GpiSetCharMode call. 

Idefine INCL_GPIPRIMITIVES /* Primitive functions */ 

linclude <os2.h> 

LONG IMode; /* character mode attribute */ 

HPS hps; /* Presentation-space handle */ 

IMode = GpiQueryCharMode(hps) ; 
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GpiQueryCharSet - 
Query Character Set 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


LONG GpiQueryCharSet (HPS hps) 


This function returns the character-set local identifier (Icid), as set by the GpiSetCharSet function. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 


Returns 

Character-set local identifier: 

LCID_DEFAULT Default 
>0 Local identifier 

LCIDERROR Error. 

Possible returns from WinGetLastError 

PMERR_INV_HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERRJNV_IN_RETAIN_MODE An attempt was made to issue a function (for example, 

query) that is invalid when the actual drawing mode is not 

draw or draw-and-retaln. 

PMERR_INV_DC_TYPE An invalid type parameter was specified with 

DevOpenDC, or a function was issued that is invalid for a 
OD_METAFILE_NOQUERY device context. 


Remarks 

This function is invalid when the drawing mode (see GpiSetDrawingMode) is set to retain. 


Related Functions 

• GpiQueryAttrs 

• GpiSetCharSet 

Example Code 

This example uses GpiQueryCharSet to return the character-set local identifier (Icid), as set by the 
GpiSetCharSet call. 

Idefine INCL_GPIPRIMITIVES /* Primitive functions */ 

linclude <os2.h> 

LONG ILcid; /* character set Icid (or error) */ 

HPS hps; /* Presentation-space handle */ 

ILcid = GpiQueryCharSet (hps) ; 
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GpiQueryCharShear - 
Query Character Shear 


^define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiQueryCharShear (HPS hps, PPOINTL pptlShear) 


This function returns the value of the current character-shear angle, as set by the GpiSetCharShear 
function. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

pptlShear (PPOINTL) - output 
Character shear. 

A point, relative to (0,0), that defines the character shear vector. 

If the character shear is currently set to the default, (0,1) is returned. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 

PMERR INV HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_IN_RETAIN_MODE An attempt was made to issue a function (for example, 

query) that is invalid when the actual drawing mode is not 

draw or draw-and-retaln. 

PMERR_INV_DC_TYPE An invalid type parameter was specified with 

DevOpenDC, or a function was issued that is invalid for a 
OD_METAFILE_NOQUERY device context. 


Remarks 

This function is invalid when the drawing mode (see GpiSetDrawingMode) is set to retain. 


Related Functions 

• GpiQueryAttrs 

• GpiSetCharShear 
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GpiQueryCharShear - 
Query Character Shear 

Example Code 

This example uses GpiQueryCharShear to return the value of the current character-shear angle, as 
set by the GpiSetCharShear call; if successful, it assigns the x coordinate of the returned vector to a 
variable. 


Idefine INCL_GPI PRIMITIVES /* Primitive functions */ 
linclude <os2.h> 

BOOL f Success; /* success indicator */ 
HPS hps; /* Presentation-space handle */ 
POINTL pptl Shear; /* character shear */ 
LONG lxCoord; /* shear angle vector x coordinate */ 


fSuccess = GpiQueryCharShear(hps, &pptl Shear); 

if (fSuccess = TRUE) 
lxCoord = pptlShear.x; 
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GpiQueryCharStringPos - 
Query Character String Positions 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiQueryCharStringPos (HPS hps, ULONG flOptlons, LONG ICount, PCH pchStrlng, 

PLONG aIXIncrements, PPOINTL aptIPosItlons) 


This function processes a string as if it is being drawn under the current character attributes using 
GpiCharStringPos, and returns the positions in the string at which each character would be drawn. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

flOptlons (ULONG) - input 
Option flag: 

CHS_VECTOR Increments vector supplied (aIXincrements). If 0, aIXincrements is ignored. 

ICount (LONG) - input 
Length of the string. 

pchStrlng (PCH) - input 

Character string to be examined. 

aIXincrements (PLONG) - input 
Vector of x increment values. 

These are signed values in world coordinates. Any negative values are treated as if they were 
0. This parameter is ignored if CHS_VECTOR is not set. 

aptIPosItlons (PPOINTL) - output 
Array of points. 

The positions of each character in world coordinates. The first point returned is the initial 
current position, and the last point is the new current position if the string has been drawn. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 


PMERRINVHPS 

PMERRPSBUSY 

PMERRINVINRETAINMODE 

PMERR_INV_CHAR_POS_OPTIONS 

PMERRJNV_LENGTH_OR_COUNT 

PMERRJNVCOORDINATE 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An attempt was made to issue a function (for example, 
query) that is invalid when the actual drawing mode is not 

draw or draw-and-retaln. 

An invalid options parameter was specified with 
GpiCharStringPos or GpiCharStringPosAt. 

An invalid length or count parameter was specified. 

An invalid coordinate value was specified. 
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GpiQueryCharStringPos - 
Query Character String Positions 

PMERR_COORDINATE_OVERFLOW An internal coordinate overflow error occurred. This can 

occur if coordinates or matrix transformation elements (or 
both) are invalid or too large. 

PMERR_INV_DC_TYPE An invalid type parameter was specified with 

DevOpenDC, or a function was issued that is invalid for a 
OD_METAFILE_NOQUERY device context. 


Remarks 

A vector of increments can be specified, allowing control over the positioning of each character after 
the first. These are distances measured in world coordinates (along the baseline for left-to-right and 
right-to-left character directions, and along the shearline for top-to-bottom and bottom-to-top). The 
i’th increment is the distance of the reference point of the (i+ 1)’th character from the reference point 
of the i’th. The last increment may be needed to update current position. 

These increments, if specified, set the widths of each character. 

This function is invalid when the drawing mode (see GpiSetDrawingMode) is set to retain. 


Related Functions 

• GpiCharString 

• GpiCharStringAt 

• GpiCharStringPos 

• GpiCharStringPosAt 

• GpiQueryCharStringPosAt 

• GpiSetCharAngle 

• GpiSetCharBox 

• GpiSetCharDirection 

• GpiSetCharMode 

• GpiSetCharSet 

• GpiSetCharShear 


Example Code 

This example calls the GpiQueryCharStringPos function to determine the location of each character 
in the string. Vector increments are not used. 


Idefine INCL_GPI PRIMITIVES /* GPI primitive functions */ 
linclude <os2.h> 


HPS hps; /* presentation space handle */ 

CHAR szString[] = "Sample string"; 

POINTL apt! [sizeof(szString) + 1]; 


GpiQueryCharStringPos (hps, /* 

OL, /* 

sizeof(szString) , /* 

szString, /* 

NULL, /* 

aptl); /* 


presentation-space handle */ 
does not use vector increments */ 
number of characters in string */ 
character string */ 
no vector increments */ 
array of structures for points */ 
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GpiQueryCharStringPosAt - 
Query Character String Positions At 


^define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiQueryCharStringPosAt (HPS hps, PPOINTL pptlStart, ULONG flOptlons, 

LONG ICount, PCH pchStrlng, PLONG aiXIncrements, 
PPOINTL aptIPosItlons) 


This function processes a string as if it is being drawn under the current character attributes using 
GpiCharStringPosAt, and returns the positions in the string at which each character would be drawn. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

pptlStart (PPOINTL) - input 
Starting position. 

flOptlons (ULONG) - input 
Option flags: 

CHS_VECTOR Increments vector supplied (aIXincrements). If 0, aIXincrements is ignored. 

ICount (LONG) - input 
Length of the string. 

pchStrlng (PCH) - input 

Character string to be examined. 

aIXincrements (PLONG) - input 
Vector of x increment values. 

These are signed values in world coordinates. Any negative values are treated as if they were 
0. This parameter is ignored if CHS_VECTOR is not set. 

aptIPosItlons (PPOINTL) - output 

Array of points, in which the positions of each character in world coordinates are returned. 

The first point returned is the initial current position, and the last point is the new current 
position if the string has been drawn. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 


PMERRINVHPS 

PMERR_PS_BUSY 

PMERRINVJNRETAINMODE 

PMERR_INV_CHAR_POS_OPTIONS 

PMERRJNVLENGTHORCOUNT 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An attempt was made to issue a function (for example, 
query) that is invalid when the actual drawing mode is not 

draw or draw-and-retain. 

An invalid options parameter was specified with 
GpiCharStringPos or GpiCharStringPosAt. 

An invalid length or count parameter was specified. 
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GpiQueryCharStringPosAt - 
Query Character String Positions At 


PMERR_INV_COORDINATE An invalid coordinate value was specified. 

PMERR_COORDINATE_OVERFLOW An internal coordinate overflow error occurred. This can 

occur if coordinates or matrix transformation elements (or 
both) are invalid or too large. 

PMERR_INV_DC_TYPE An invalid type parameter was specified with 

DevOpenOC, or a function was issued that is invalid for a 
OD_METAFILE_NOQUERY device context. 


Remarks 

A vector of increments can be specified, allowing control over the positioning of each character after 
the first. These are distances measured in world coordinates (along the baseline for left-to-right and 
right-to-left character directions, and along the shearline for top-to-bottom and bottom-to-top). The 
i’th increment is the distance of the reference point of the (i + 1 )’th character from the reference point 
of the i’th. The last increment may be needed to update current position. 

These increments, if specified, set the widths of each character. 

This function is invalid when the drawing mode (see GpiSetDrawingMode) is set to retain. 


Related Functions 

• GpiCharString 

• GpiCharStringAt 

• GpiCharStringPos 

• GpiCharStringPosAt 

• GpiQueryCharStringPos 

• GpiSetCharAngle 

• GpiSetCharBox 

• GpiSetCharDirection 

• GpiSetCharMode 

• GpiSetCharSet 

• GpiSetCharShear 

Example Code 

This example uses the GpiQueryCharStringPosAt function to determine the location of each 
character in the string. Vector increments are not used. 

Idefine INCL_GPIPRIMITIVES /* GPI primitive functions */ 
linclude <os2.h> 

HPS hps; /* presentation space handle */ 

POINTL ptl Start = { 100, 100 }; 

POINTL aptl [12] ; 

GpiQueryCharStringPosAt (hps, /* 

&ptl Start, /* 

0L, /* 

1 1 L , /* 

"This string", /* 

NULL, /* 

aptl); /* 


presentation-space handle */ 
starting point for string */ 
do not use vector increments */ 
11 characters in string */ 
character string */ 
no vector increments */ 


array of structures for points */ 
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GpiQueryClipBox - 
Query Clip Box 


#define INCL.GPIREGIONS /* Or use INCL_GPI or INCL_PM */ 


LONG GpiQueryClipBox (HPS hps, PRECTL prcIBound) 


This function returns the dimensions of the tightest rectangle which completely encloses the 
intersection of all the clipping definitions. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

prcIBound (PRECTL) - output 
Bounding rectangle. 

The coordinates of the bounding rectangle, in world coordinates. 


Returns 

Complexity and error indicators: 
RGN_NULL Null region 

RGN_RECT Rectangular region 

RGN_COMPLEX Complex region 
RGN ERROR Error. 


Possible returns from WinGetLastError 

PMERRINV HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_COORDINATE_OVERFLOW An internal coordinate overflow error occurred. This can 

occur if coordinates or matrix transformation elements (or 
both) are invalid or too large. 


Remarks 

The clipping definitions include the combined effects of: 

• Clip path 

• Viewing limits 

• Graphics field 

• Clip region 

• Visible region (windowing considerations). 

Points on the borders of the rectangle returned are considered to be included within the rectangle. If 
the intersection is null, the rectangle returned has the right boundary less than the left, and the top 
boundary less than the bottom. 
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GpiQueryClipBox 
Query Clip Box 


Example Code 

This example uses GpiQueryClipBox to return the dimensions of the tightest rectangle which 
completely encloses the intersection of all the clipping definitions. The example queries the clip box 
and, if a rectangular region is returned, assigns the x coordinate of the lower left hand corner of the 
clip box region to a variable. 


Idefine INCL_GPIREGIONS /* Region functions */ 
linclude <os2.h> 

LONG 1 Complexity; /* complexity/error indicator */ 
HPS hps; /* Presentation-space handle */ 
RECTL prcl Bound; /* bounding rectangle */ 


LONG 1 LwrLftxCoord; /* lower left x coordinate of clip box */ 
IComplexity = GpiQueryClipBox (hps, SprclBound); 

/* if returned region is a rectangle, assign lower left x coordinate */ 
if (IComplexity == RGN_RECT) 

1 LwrLftxCoord = prcl Bound. xLeft; 
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GpiQueryClipRegion - 
Query Clip Region 


#define INCL_GPIREGIONS /* Or use INCL_GPI or INCL_PM */ 


HRGN GpiQueryClipRegion (HPS hps) 


This function returns the handle of the currently selected clip region. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 


Returns 

Clip-region handle (if any): 

NULLHANDLE Null handle (no region is selected) 

HRGN_ERROR Error 
Otherwise Clip region handle. 

Possible returns from WinGetLastError 

PMERR INV HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

Remarks 

If there is no currently selected clip region, a null handle is returned. 

Example Code 

This example uses GpiQueryClipRegion to return the handle of the currently selected clip region. 

Idefine INCL_GPIREGIONS /* Region functions */ 

linclude <os2.h> 

HPS hps; /* Presentation-space handle */ 

HRGN hrgn; /* clip region handle */ 

hrgn = GpiQueryCl ipRegion(hps) ; 
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GpiQueryColor 
Query Color 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM. Also in COMMON section */ 


LONG GpiQueryColor (HPS hps) 


This function returns the current value of the (character) color attribute, as set by the GpiSetColor 
call. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 


Returns 

Color attribute: 


CLR_ERROR Error 

CLR_DEFAULT Default 
Otherwise Color index. 


Possible returns from WinGetLastError 

PMERRJNV HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_IN_RETAIN_MODE An attempt was made to issue a function (for example, 

query) that is invalid when the actual drawing mode is not 

draw or draw-and-retaln. 

PMERR INV_DC_TYPE An invalid type parameter was specified with 

DevOpenDC, or a function was issued that is invalid for a 
OD_METAFILE_NOQUERY device context. 


Remarks 

This function is invalid when the drawing mode (see GpiSetDrawingMode) is set to retain. 


5-262 


PM Programming Reference 




GpiQueryColor - 
Query Color 


Example Code 

This example uses GpiQueryColor to return the current value of the (character) color attribute, then 
sets the color to red by calling GpiSetColor. When finished with red, the color is set back to its 
original value. 

Idefine INCL_GPIPRIMITIVES /* Primitive functions */ 

linclude <os2.h> 

LONG 1 Col or; /* current character color (or error) */ 

HPS hps; /* Presentation-space handle */ 

HPS GEhps; 

/* query current color */ 

IColor = GpiQueryColor(hps) ; 

/* set color to red */ 

GpiSetColor(GEhps, CLR_RED); 


/* restore to original color */ 
GpiSetColor(GEhps, IColor); 
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GpiQueryColorData - 
Query Color Data 


#define INCL_GPILOGCOLORTABLE /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiQueryColorData (HPS hps, LONG ICount, PLONG alArray) 


Information about the current logical color table or the selected palette is returned by this function. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

ICount (LONG) - input 
Number of elements. 

Number of elements supplied in alArray. 

alArray (PLONG) - output 
Array. 

On return this array contains: 

Array[QCD_LCT_FORMAT] Format of loaded color table if any. One of the following values is 

returned: 

LCOLFDEFAULT Default color table is in force. 

LCOLFJNDRGB Color table loaded which provides translation 
from index to RGB. 

LCOLF_RGB Color index = RGB. 

LCOLF PALETTE Palette is selected. 

Array[QCD_LCT_LOINDEX] Smallest color index in the color table or palette ; always zero for 

color tables. 

Array[QCD_LCT_HIINDEX] Largest color index in the color table or palette ; never less than 

15 for color tables. 

Array[QCD_LCT_OPTIONS] Color table or palette option. Zero or more of the following are 

returned: 

LCOL PURECOLOR No color dithering (color table or selected 
palette ). 

LCOL OVERRIDE DEFAULT COLORS Override for applications 
that need the full hardware palette (selected 
palette only) 

The array elements are numbered consecutively, starting with 
Array[QCD_LCT_FORMAT]. The element number constants start 
with 0. (See the appropriate Bindings Reference.) 

Information is returned only for the number of elements supplied. 
Any extra elements supplied, beyond those described above, are 
set to zero by the system. 
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GpiQueryColorData - 
Query Color Data 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERR_INV_HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_LENGTH_OR_COUNT An invalid length or count parameter was specified. 

Example Code 

This example uses the GpiQueryColorData function to retrieve the smallest color-table index. The 
GpiQueryLogColorTable function is then used to retrieve the RGB color value for this index. 


Idefine INCL_GPILOGCOLORTABLE /* Color Table functions */ 
linclude <os2.h> 

HPS hps; /* presentation space handle */ 
LONG alData[3]; /* information array */ 
LONG alColor[l]; /* information array */ 


GpiQueryColorData (hps, 3L, alData); 
GpiQueryLogColorTable(hps, 0L, a 1 Data [QCD_LCT_L0 INDEX] , 

1L, alColor); 
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GpiQueryColorlndex 
Query Color Index 


#define INCL_GPILOGCOLORTABLE /* Or use INCL_GPI or INCL_PM */ 


LONG GpiQueryColorlndex (HPS hps, ULONG ulOptions, LONG IRgbColor) 


This function returns the color index of the device color that is closest to the specified RGB color 
representation for the device connected to the specified presentation space. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

ulOptions (ULONG) - input 
Options: 

Reserved, and must be zero. 

IRgbColor (LONG) - input 

Specifies a color in RGB terms. 


Returns 

Color index providing closest match to the specified color: 
>0 Color index 

GPI_ALTERROR Error. 

Possible returns from WinGetLastError 

PMERRJNVHPS 
PMERRPSBUSY 

PMERR_INV_COLOR_OPTIONS 

PMERR INV RGBCOLOR 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid options parameter was specified with a logical 
color table or color query function. 

An invalid rgb color parameter was specified with 
GpiQueryNearestColor or GpiQueryColor 


Remarks 

If an RGB logical color table has been loaded, this call returns the same RGB color that is passed to 
it. 
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GpiQueryColorlndex - 
Query Color Index 


Example Code 

This example uses GpiQueryColorlndex to return the color index of the device color that is closest to 
the specified RGB color representation for the device connected to the specified presentation space. 


Idefine INCL_GPILOGCOLORTABLE /* Color Table functions */ 
linclude <os2.h> 

LONG 1 Index; /* closest match color index */ 
HPS hps; /* Presentation-space handle */ 
ULONG ul Options; /* options */ 
LONG lRgbColor; /* color in RGB terms */ 


/* reserved; set to 0 */ 
ulOptions = 0L; 

/* color to find index for */ 

lRgbColor = (PC_RESERVED*16777216) + (0*65536) + (0*256) + 1; 
1 Index = GpiQueryColorIndex(hps, ulOptions, lRgbColor); 
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GpiQueryCp - 
Query Code Page 


#define INCL_GPILCIDS /* Or use INCL_GPI or INCL_PM */ 


ULONG GpiQueryCp (HPS hps) 


This function returns the currently selected graphics code page. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 


Returns 

Code page: 

GPIJERROR Error 
Otherwise Code page. 

Possible returns from WinGetLastError 

PMERR INV HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

Remarks 

The code page identity returned is the one that is set by GpiSetCp (or defaulted when the 
presentation space is first created). This is the code page of the default font, not the 
currently-selected font, found from GpiQueryFontMetrics. 

Example Code 

This example uses GpiQueryCp to return the currently selected graphics code page. 

Idefine INCL_GPI LCIDS /* Font functions */ 

linclude <os2.h> 

ULONG ul CodePage; /* code page (or error) */ 

HPS hps; /* Presentation-space handle */ 

ul CodePage = GpiQueryCp(hps) ; 


5-268 


PM Programming Reference 






GpiQueryCurrentPosition - 
Query Current Position 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiQueryCurrentPosition (HPS bps, PPOINTL pptIPoInt) 


This function returns the value of current position. 


Parameters 

bps (HPS) - input 

Presentation-space handle. 

pptIPoInt (PPOINTL) - output 
Current position. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An attempt was made to issue a function (for example, 
query) that is invalid when the actual drawing mode is not 

draw or draw-and-retaln. 

An invalid type parameter was specified with 
DevOpenDC, or a function was issued that is invalid for a 
OD_METAFILE_NOQUERY device context. 


Possible returns from WinGetLastError 

PMERRINVHPS 

PMERRPSBUSY 

PMERRINVINRETAINMODE 

P M E RRJN V_DC_T YPE 


Remarks 

This function is invalid when the drawing mode (see GpiSetDrawingMode) is set to retain. 


Example Code 

This example uses GpiQueryCurrentPosition to return the value of the current position and assigns 
the x coordinate to a variable. 


Idefine INCL_GPIPRIMITIVES /* Primitive functions */ 
linclude <os2.h> 

BOOL fSuccess; /* success indicator */ 
HPS hps; /* Presentation-space handle */ 
POINTL pptl Point; /* current position */ 
LONG lxCoord; /* current position x coordinate */ 


fSuccess = GpiQueryCurrentPosition(hps, &pptlPoint); 

if (fSuccess == TRUE) 
lxCoord = pptlPoint.x; 
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GpiQueryDefArcParams - 
Query Default Arc Parameters 


#define INCL_GPIDEFAULTS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiQueryDefArcParams (HPS hps, PARCPARAMS parcpArcParams) 


This function returns the default values of the arc parameters, as set by the GpiSetDefArcParams 
function. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

parcpArcParams (PARCPARAMS) - output 
Default arc parameters. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERR_INV_HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

Example Code 

This example uses GpiQueryDefArcParams to return the default values of the arc parameters, as set 
by the GpiSetDefArcParams call, and assign a variable to the P coefficient if the query succeeds. 


Idefine INCL_GPIDEFAULTS /* Default functions */ 
linclude <os2.h> 

BOOL f Success; /* success indicator */ 
HPS hps; /* Presentation-space handle */ 
ARCPARAMS parcpArcParams; /* Arc parameters */ 


LONG 1 Pcoefficient; /* p coefficient of arc definition */ 

fSuccess = GpiQueryDefArcParams (hps, SparcpArcParams) ; 

/* if successful, assign value of P coefficient */ 
if (fSuccess == TRUE) 

lPcoefficient = parcpArcParams. IP; 
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GpiQueryDefAttrs - 
Query Default Attributes 


#define INCL_GPIDEFAULTS /* Or use INCL_GPI or INCL_PM */ 

BOOL GpiQueryDefAttrs (HPS hps, LONG IPrlmType, ULONG flAttrMask, 

PBUNDLE ppbunAttrs) 

This function returns default attribute values for the specified primitive type. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

IPrlmType (LONG) - input 
Primitive type. 

This is the type of primitive for which default attribute values are to be queried, as follows: 

PRIM_LINE Line and arc primitives 

PRIM_CHAR Character primitives 

PRIM_MARKER Marker primitives 

PRIM_AREA Area primitives 

PRIMJMAGE Image primitives. 

flAttrMask (ULONG) - input 

Attributes mask. 

Each flag that is set indicates that the default value of the corresponding attribute is to be 
returned in the ppbunAttrs buffer. 

If all flags in flAttrMask are 0, the ppbunAttrs buffer address is not used. 

ppbunAttrs (PBUNDLE) - output 
Attributes. 

ppbunAttrs is a buffer in which is returned the default value of each attribute for which the 
flAttrMask flag is set, in the order specified in GpiSetAttrs for the particular primitive type. 

Only data for attributes for which the appropriate flag in flAttrMask is set is updated, so 
ppbunAttrs need only be large enough for the highest offset attribute to be returned (see 
GpiSetAttrs). 

Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRJNVHPS 
PMERRPSBUSY 

PMERR_INV_PRIMITIVE_TYPE 

PMERRUNSUPPORTEDATTR 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid primitive type parameter was specified with 
GpiSetAttrs or GpiQueryAttrs. 

An unsupported attribute was specified in the attrmask 
with GpiSetAttrs or GpiQueryAttrs. 
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GpiQueryDefAttrs - 
Query Default Attributes 


Remarks 

The parameters returned by this function may be used to reinstate exactly the same default attribute 
values as are queried, using GpiSetDefAttrs. 

Example Code 

This example uses GpiQueryDefAttrs to return the default color and mix attribute values for the 
primitive line and arc types and, if successful, uses the values to reinstate the default attributes via 
the DosSetDefAttrs API. 


Idefine INCL_GPIDEFAULTS /* Default functions */ 
linclude <os2.h> 

BOOL f Success; /* success indicator */ 
HPS hps; /* Presentation-space handle */ 
LONG IPrimType; /* primitive type */ 
ULONG flAttrMask; /* attributes mask */ 
LINEBUNDLE ppbunAttrs; /* Attributes */ 


/* request line/arc primitive values */ 

IPrimType = PRIM_LINE; 

/* request values for color, mix attributes */ 
flAttrMask = LBB_C0L0R | LBB_MIX_MODE; 

fSuccess = GpiQueryDefAttrs (hps, IPrimType, flAttrMask, 

&ppbunAttrs) ; 

/* if successful, reinstate default color and mix attributes */ 
if (fSuccess == TRUE) 

fSuccess = GpiSetDefAttrs (hps, IPrimType, flAttrMask, 

&ppbunAttrs) ; 
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GpiQueryDefauItViewMatrix - 
Query Default View Matrix 

#define INCL_GPITRANSFORMS /* Or use INCL_GPI or INCL_PM */ 

BOOL GpiQueryDefauItViewMatrix (HPS hps, LONG ICount, PMATRIXLF pmatlf Array) 

This function returns the current default viewing transform; see GpiSetDefauitViewMatrix. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

ICount (LONG) - input 
Number of elements. 

The number of elements to be returned in pmatlf Array ; must be in the range 0 through 9. If 0 is 
specified, no matrix elements are returned. 

pmatlfArray (PMATRIXLF) - output 
Transform matrix. 

An array into which the elements of the default viewing transform matrix are returned. 

Returns 

Success indicator; 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRJNVHPS 
PMERRPSBUSY 

PMERR_INV_LENGTH_OR_COUNT 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid length or count parameter was specified. 
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GpiQueryDefauItViewMatrix - 
Query Default View Matrix 

Example Code 

This example uses GpiQueryDefauItViewMatrix to return the default viewing transform and, if 
successful, defines - via DosSetDefauItViewMatrix - the returned value as the new default transform. 


Idefine INCL_GPITRANSFORMS /* Transform functions */ 
finclude <os2.h> 

BOOL fSuccess; /* success indicator */ 
HPS hps; /* Presentation-space handle */ 
LONG 1 Count; /* number of elements */ 
MATRIXLF pmatlf Array; /* transform matrix */ 
LONG 1 Options; /* set default options */ 


1 Count = 1; /* examine only first element of transform matrix */ 

fSuccess = GpiQueryDefauItViewMatrix (hps, ICount, &pmatl f Array ) ; 

/* set default to returned transform */ 
if (fSuccess == TRUE) 

{ 

1 Options = TRANSFORM_REPLACE; 

fSuccess = GpiSetDefaultViewMatrix(hps, ICount, &pmatlfArray, 
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GpiQueryDefCharBox - 
Query Default Graphics Character Box 


^define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiQueryDefCharBox (HPS hps, PSIZEL psIziSize) 


This function returns the size of the default graphics character box in world coordinates. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

psIziSize (PSIZEL) - output 
Default character-box size. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 

PMERR INV HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_IN_RETAIN_MODE An attempt was made to issue a function (for example, 

query) that is invalid when the actual drawing mode is not 

draw or draw-and-retain. 


Remarks 

The values returned are the same as the initial default value of the character-box attribute. See 
GpiSetCharBox for further information. 
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GpiQueryDefCharBox - 

Query Default Graphics Character Box 

Example Code 

This example uses GpiQueryDefCharBox to query the initial size of the default graphics character 
box in world coordinates and, if the query succeeds, resets the current size back to this initial default 
value via GpiSetCharBox (note the required transformation from LONG to FIXED using the 
MAKEFIXED macro). 


Idefine INCL_GPIPRIMITIVES /* Primitive functions */ 
linclude <os2.h> 

BOOL f Success; /* success indicator */ 
HPS hps; /* Presentation-space handle */ 
SIZEL psizlSize; /* default character-box size */ 
SIZEF psizfxSize; /* new character-box size */ 


fSuccess = GpiQueryDefCharBox (hps, &psizlSize); 

/* if successful, set current box size to initial default value */ 
if (fSuccess == TRUE) 

{ 

psizfxSize. cx = MAKEFIXED(psizlSize. cx, 0x0000) ; 
psizfxSize. cy = MAKEFIXED(psizlSize.cy ,0x0000) ; 
GpiSetCharBox(hps, SpsizfxSize) ; 

} 
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GpiQueryDefTag - 
Query Default Tag 


#define INCL_GPIDEFAULTS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiQueryDefTag (HPS hps, PLONG pITag) 


This function returns the default value of the tag identifier, as set by the GpiSetDefTag function. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

pITag (PLONG) - output 
Default tag identifier. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRINV HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_MICROPS_FUNCTION An attempt was made to issue a function that is invalid in 

a micro presentation space. 


Example Code 

This example uses GpiQueryDefTag to return the default value of the tag identifier, as set by the 
GpiSetDefTag call. 


Idefine INCL_GPIDEFAULTS /* Default functions */ 
linclude <os2.h> 

BOOL fSuccess; /* success indicator */ 
HPS hps; /* Presentation-space handle */ 
LONG pITag; /* default tag identifier */ 


fSuccess = GpiQueryDefTag(hps, &plTag); 
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GpiQueryDefViewingLimits - 
Query Default Viewing Limits 


#define INCL_GPIDEFAULTS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiQueryDefViewingLimits (HPS hps, PRECTL prcILImlts) 


This function returns the default value of the viewing limits, as set by the GpiSetDefViewingLimits 
function. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

prcILImlts (PRECTL) - output 
Default viewing. limits. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERR INV_HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 


Example Code 

This example uses GpiQueryDefViewingLimits to return the default value of the viewing limits, as set 
by the GpiSetDefViewingLimits and, if the query succeeds, assigns a variable to the x coordinate of 
the lower left hand corner of the viewing limits rectangle. 


Idefine INCL_GPIDEFAULTS /* Default functions */ 
linclude <os2.h> 

BOOL fSuccess; /* success indicator */ 
HPS hps; /* Presentation-space handle */ 
RECTL prcl Limits; /* default viewing limits */ 
LONG lLwrLftxCoord; /* lower left x coordinate of limit */ 


fSuccess = GpiQueryDefViewingLimits(hps, SprclLimits); 

/* if successful, assign lower left x coordinate of viewing limit */ 
if (fSuccess == TRUE) 

lLwrLftxCoord = prclLimits.xLeft; 
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GpiQueryDevice - 
Query Device 


#define INCL_GPICONTROL /* Or use INCL_GPI or INCL_PM. Also in COMMON section */ 


HDC GpiQueryDevice (HPS hps) 


This function returns the handle of the currently associated device context. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 


Returns 

Device-context handle: 

HDCERROR Error 

NULLHANDLE No device context is currently associated 
Otherwise Device context handle. 

Possible returns from WinGetLastError 

PMERR_INV_HPS An invalid presentation-space handle was specified. 

PMERRJNV_HDC An invalid device-context handle or (micro presentation 

space) presentation-space handle was specified. 

Example Code 

This example uses the GpiQueryDevice function to retrieve a device-context handle for the 
presentation space of the desktop window. The handle is used in the DevQueryCaps function to 
determine the width and height of the Presentation Manager screen. 


Idefine INCL_GPICONTROL /* GPI control Functions */ 
Idefine INCL_WINWINDOWMGR /* Window Manager Functions */ 
Idefine INCL_DEV /* Device Function definitions */ 
linclude <os2.h> 

HPS hps; /* presentation space handle */ 
HDC hdc; /* device context handle */ 
LONG 1 Width, 1 Height; 


hps = WinGetScreenPS(HWND_DESKTOP) ; 
hdc = GpiQueryDevice(hps) ; 

DevQueryCaps (hdc, CAPS_WIDTH, 1L, aiWidth); 
DevQueryCaps (hdc, CAPS_H EIGHT, 1L, &lHeight); 


Chapter 5. Graphics Functions 5-279 





GpiQueryDeviceBitmapFormats 
Query Device Bit-Map Formats 


#define INCL_GPIBITMAPS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiQueryDeviceBitmapFormats (HPS hps, LONG ICount, PLONG alArray) 


This function returns the formats of bit maps supported internally by the device driver. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

The associated device context defines the class of device for which formats are required. This 
must be either a memory device context or a device context for a device that supports raster 
operations. 

ICount (LONG) - input 
Number of elements. 

Number of elements in alArray (must be an even number). For the complete set of formats 
returned, the value of this parameter must be at least double the number of device formats 
returned by DevQueryCaps. 

alArray (PLONG) - output 
Data array. 

Array of elements that, on return, is set to pairs of ( cPIanes , cB/'fCounf)elements (see 
BITMAPINFOHEADER) for each supported format in turn. Any unused elements are set to 0. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRINVHPS 
PMERRPSBUSY 

PMERR_INV_LENGTH_OR_COUNT 

Remarks 

An application can create, set, and query bit maps using any of the standard formats. Internally, 
however, these are converted by the device driver into one of the device internal formats if 
necessary. This is normally a smaller set than the standard set of bit-map formats. 

The number of device bit-map formats can be found with DevQueryCaps (CAPS_BITMAP_FORMATS). 

The first pair of ( cPIanes , cBitCount) elements returned most closely matches the device. 

This function must not be issued when there is no device context associated with the presentation 
space. 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid length or count parameter was specified. 


5-280 PM Programming Reference 







GpiQueryDeviceBitmapFormats - 
Query Device Bit-Map Formats 


Example Code 

This example uses the GpiQueryDeviceBitmapFormats function to retrieve bit-map formats for the 
screen and creates a screen-compatible bit map with GpiCreateBitmap. 


Idefine INCL_GPIBITMAPS /* GPI Bit-map functions */ 

linclude <os2.h> 


HPS 

hps; 

/* 

Target presentation-space handle 

*/ 

LONG 

1 Formats [24] ;/* Formats supported by the device 

*/ 

HBITMAP 

hbm; 

/* 

Bit-map handle 

*/ 

PBYTE 

pb; 

/* 

Bit-map image data 

.*/ 

BITMAPINF02 

pbmlnfo; 

/* 

Bit-map information table 

*/ 


/* Get screen supportable formats */ 
GpiQueryDeviceBitmapFormats(hps, 24L, lFormats); 


/**************************** 

* set bitmapinfo structure * 

**************************** j 

pbmlnfo.cbFix = 16L; 
pbmlnfo.cx = 100L; 
pbmlnfo.cy = 100L; 

pbmlnfo.cPlanes = (USHORT) lFormats[0] ; 
pbmlnfo.cBitCount = (USHORT) 1 Formats [1]; 


/* create bit map and return handle */ 

hbm = GpiCreateBitmap(hps, /* presentation space */ 

(PBITMAPINF0HEADER2)&pbmInfo, 

/* bit-map information header */ 
CBM_INIT, /* initialize the bit map */ 

pb, /* bit-map data */ 

Spbrnlnfo); /* bit-map information table */ 


Chapter 5. Graphics Functions 5-281 



GpiQueryDrawControl 
Query Draw Control 


^define INCL_GPICONTROL /* Or use INCL_GPI or INCL_PM */ 


LONG GpiQueryDrawControl (HPS hps, LONG IControl) 


This function returns a drawing control as set by GpiSetDrawControl. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

IControl (LONG) - input 

Control whose value is to be returned: 


DCTL_ERASE 
DCTL_DISPLAY 
DCTLBOUNDARY 
DCTLDYNAMIC 
DCTL CORRELATE 


Erase before draw 
Display 

Accumulate boundary data 
Draw dynamic segments 
Correlate. 


Returns 

Value of the control. 

(See GpiSetDrawControl for details): 

DCTL_OFF Off 

DCTL_ON On 

DCTL_ERROR Error. 


Possible returns from WinGetLastError 


PMERRINVHPS 

PMERRPSBUSY 

PMERRINVDRAWCONTROL 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid control parameter was specified with 
GpiSetDrawControl or GpiQueryDrawControl. 


PMERR_INV_MICROPS_DRAW_CONTROL A draw control parameter was specified with 

GpiSetDrawControl that is invalid in a micro presentation 
space. 
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GpiQueryDrawControl - 
Query Draw Control 


Example Code 

This example uses GpiQueryDrawControl to return the value for the Display drawing control as set 
by GpiSetDrawControl. 


# define INCL_GPICONTROL /* Control functions */ 
linclude <os2.h> 

LONG lValue; /* value of the control */ 
HPS hps; /* Presentation-space handle */ 
LONG 1 Control; /* control value to be queried */ 


/* ask for Display control value */ 

1 Control = DCTL_DISPLAY; 

lValue = GpiQueryDrawControl (hps, 1 Control); 


Chapter 5. Graphics Functions 5-283 



GpiQueryDrawingMode 
Query Drawing Mode 


#define INCL_GPICONTROL /* Or use INCL_GPI or INCL_PM */ 


LONG GpiQueryDrawingMode (HPS hps) 


This function returns the current drawing mode, as set by GpiSetDrawingMode. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 


Returns 

Drawing mode. 

(See GpiSetDrawingMode for details): 

>0 Drawing mode 

DM_ERROR Error. 

Possible returns from WinGetLastError 

PMERR INV HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_MICROPS_FUNCTION An attempt was made to issue a function that is invalid in 

a micro presentation space. 

Example Code 

This example uses GpiQueryDrawingMode to return the current drawing mode, as set by 
GpiSetDrawingMode. 

Idefine INCL_GPICONTROL /* Control functions */ 

linclude <os2.h> 

LONG IMode; /* drawing mode */ 

HPS hps; /* Presentation-space handle */ 

IMode = GpiQueryDrawingMode (hps); 
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GpiQueryEditMode - 
Query Edit Mode 


#define INCL_GPISEGEDITING /* Or use INCL_GPI or INCL_PM */ 


LONG GpiQueryEditMode (HPS hps) 


This function returns the current editing mode, as set by GpiSetEditMode. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 


Returns 

Current editing mode: 

SEGEMJNSERT Insert mode 

SEGEM_REPLACE Replace mode 
SEGEM_ERROR Error. 

Possible returns from WinGetLastError 

PMERRJNV HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERRJNV_MICROPS_FUNCTION An attempt was made to issue a function that is invalid in 

a micro presentation space. 


Remarks 

This function can be issued in any drawing mode. 

Example Code 

This example uses GpiQueryEditMode to return the current editing mode, as set by GpiSetEditMode. 

Idefine INCL_GPISEGEDITING /* Segment Editing functions */ 
linclude <os2.h> 

LONG IMode; /* editing mode */ 

HPS hps; /* Presentation-space handle */ 

IMode = GpiQueryEditMode(hps) ; 
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GpiQueryElement - 
Query Element 


#define INCLGPISEGEDITING /* Or use INCL_GPI or INCL_PM 7 

LONG GpiQueryElement (HPS hps, LONG lOff, LONG IMaxLength, PBYTE pbData) 

This function returns element content data. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

lOff (LONG) - input 

Starting byte offset within the element. 

IMaxLength (LONG) - input 

Maximum length of data that can be returned. 

pbData (PBYTE) - output 
Element content data. 

An area of IMaxLength bytes in which the element content data is to be returned. 

Returns 

Number of bytes returned: 

>0 Actual number of bytes returned 

GPI_ALTERROR Error. 

Possible returns from WinGetLastError 

PMERRJNVHPS 
PMERRPSBUSY 

PMERRINVMICROPSFUNCTION 

PMERRNOCURRENTELEMENT 

PMERRNOTINRETAINMODE 

PMERR_INV_LENGTH_OR_COUNT 
PMERRINVINELEMENT 

PMERR_INV_ELEMENT_OFFSET 

PMERRNOCURRENTSEG 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An attempt was made to issue a function that is invalid in 
a micro presentation space. 

An attempt has been made to issue 
GpiQueryElementType or GpiQueryElement while there is 
no currently open element. 

An attempt was made to issue a segment editing element 
function that is invalid when the actual drawing mode is 
not set to retain 

An invalid length or count parameter was specified. 

An attempt was made to issue a function invalid inside an 
element bracket. 

An invalid off (offset) parameter was specified with 
GpiQueryElement. 

An attempt has been made to issue 
GpiQueryElementType or GpiQueryElement while there is 
no currently open segment. 
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GpiQueryElement - 
Query Element 

Remarks 

Returns the element content (or part of the element content) for the element to which the element 
pointer currently points. 

This function is only valid when the drawing mode (see GpiSetDrawingMode) is set to retain (not 
draw-and-retaln), and a segment bracket is currently in progress. 

This function is not valid within an element bracket. 

Example Code 

This example uses the GpiQueryElement function to retrieve the graphics-order data for an element. 

Idefine INCL_GPISEGEDITING /* GPI Segment Edit functions */ 
linclude <os2.h> 


HPS hps; /* presentation space handle */ 

BYTE abElement[512] ; /* element data buffer */ 

/* Move pointer to first element in segment. */ 

GpiSetElementPointer(hps, 1L); 

GpiQueryElement(hps, /* presentation space */ 

0L, /* start with first byte in element */ 

512L, /* copy no more than 512 bytes */ 

abElement); /* buffer to receive data */ 
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GpiQueryElementPointer 
Query Element Pointer 


#define INCLJ3PISEGEDITING /* Or use INCL_GPI or INCL_PM */ 


LONG GpiQueryElementPointer (HPS hps) 


This function returns the current element pointer. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 


Returns 

Current element pointer: 

>0 Current element pointer 

GPI_ALTERROR Error. 

Possible returns from WinGetLastError 

PMERRJNVHPS 
PMERRPSBUSY 

PMERRINVMICROPSFUNCTION 

PMERRNOTINRETAINMODE 

PMERRNOCURRENTSEG 

Remarks 

This function is only valid when the drawing mode (see GpiSetDrawingMode) is set to retain (not 
draw-and-retaln), and a segment bracket is currently in progress. 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An attempt was made to issue a function that is invalid in 
a micro presentation space. 

An attempt was made to issue a segment editing element 
function that is invalid when the actual drawing mode is 
not set to retain 

An attempt has been made to issue 
GpiQueryElementType or GpiQueryElement while there is 
no currently open segment. 
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GpiQueryElementPointer - 
Query Element Pointer 


Example Code 

This example uses GpiQueryElementPointer to return the current element pointer after setting the 
Draw mode to retain and beginning a graphics segment named 1. 

fdefine INCL_GPISEGEDITING /* Segment Editing functions */ 


fdefine INCL_GPICONTROL /* Control functions */ 
fdefine INCL_GPISEGMENTS /* Segment functions */ 
finclude <os2.h> 

LONG 1 Element; /* current element pointer */ 
HPS hps ; /* Presentation-space handle */ 


/* set the draw mode to retain and open the segment */ 
if (Gpi SetDrawingMode(hps, DM_RETAIN) == TRUE && 
GpiOpenSegment(hps, 1L) == TRUE) 

{ 

lElement = GpiQueryElementPointer(hps) ; 
GpiCloseSegment(hps) ; /* close the segment */ 

} 
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GpiQueryElementType 
Query Element Type 


#define INCL_GPISEGEDITING /* Or use INCL_GPI or INCL_PM */ 


LONG GpiQueryElementType (HPS hps, PLONG pIType, LONG ILength, PSZ pszData) 


This function returns information about the element to which the element pointer currently points. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

pIType (PLONG) - output 
Element type. 

The element type can be system-defined or application-defined; see GpiElement and 
GpiBeginElement. 

ILength (LONG) - input 
Data length. 

Length of the description data buffer. 

pszData (PSZ) - output 

Description of data buffer. 

The description may be system-defined or application-defined; see GpiElement and 
GpiBeginElement. The string is null-terminated, even if it has to be truncated. 


Returns 

Size of the data required to hold the element content. 

This can be used for a subsequent GpiQueryElement function. 
>0 Size of data 

GPI_ALTERROR Error. 


Possible returns from WinGetLastError 


PMERRINVHPS 

PMERRPSBUSY 

PMERRINVMICROPSFUNCTION 

PMERRNOCURRENTELEMENT 

PMERRNOTINRETAINMODE 

PMERR_INV_LENGTH_OR_COUNT 

PMERRINVINELEMENT 

PMERRNOCURRENTSEG 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An attempt was made to issue a function that is invalid in 
a micro presentation space. 

An attempt has been made to issue 
GpiQueryElementType or GpiQueryElement while there is 
no currently open element. 

An attempt was made to issue a segment editing element 
function that is invalid when the actual drawing mode is 
not set to retain 

An invalid length or count parameter was specified. 

An attempt was made to issue a function invalid inside an 
element bracket. 

An attempt has been made to issue 
GpiQueryElementType or GpiQueryElement while there is 
no currently open segment. 
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GpiQueryElementType - 
Query Element Type 


Remarks 

This function is only valid when the drawing mode (see GpiSetDrawingMode) is set to retain (not 
draw-and-retaln), and a segment bracket is currently in progress. It is not valid in an element 
bracket. 

Example Code 

This example uses the GpiQueryElementType function to retrieve the size of the current element. 
The size is used to retrieve the graphics-order data in the element. 

Idefine INCL_GPISEGEDITING /* GPI Segment Edit functions */ 
finclude <os2.h> 

HPS hps; /* presentation space handle */ 

BYTE abElement[512] ; 

LONG cbElement; 

LONG Hype; 

/* move pointer to first element in segment */ 

GpiSetElementPointer(hps, 1L); 
cbElement = Gpi Query El ementType( 

hps, /* presentation space */ 

UlType, /* variable to receive type */ 

0L, /* copy zero bytes of description */ 

NULL); /* no buffer for description */ 

Gpi Query Element (hps, 0L, cbElement, abElement); 
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GpiQueryFaceString 
Query Face String 


#define INCL_GPILCIDS /* Or use INCL_GPI or INCL_PM */ 


ULONG GpiQueryFaceString (HPS hps, PSZ pszFamllyName, 

PFACENAMEDESC pfndFaceAttrs, LONG ILength, 
PSZ pszCompoundFaceName) 


This function generates a compound face name for a font. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

pszFamllyName (PSZ) - input 
Family name. 

The family name of the font (for example, “Courier”). 

pfndFaceAttrs (PFACENAMEDESC) - input 
Face-name description. 

A structure that provides the characteristics of the required font. These characteristics are used 
to generate the compound face name. 

ILength (LONG) - input 

Length of pszCompoundFaceName buffer. 

The maximum length of the compound face name returned (including the trailing zero of the 
string). 

Specify zero to find out how large the pszCompoundFaceName buffer needs to be. 

pszCompoundFaceName (PSZ) - output 
Compound face name. 

The compound face name of the font. 


Returns 

Length of the compound face name: 

GPI_ERROR Error occurred 

> 0 Length of the compound face-name string (including the trailing zero). This is the 

length of the complete string; if it is greater than ILength, the string returned in 
pszCompoundFaceName is truncated. 

Possible returns from WinGetLastError 

PMERR_FONT_NOT_LOADED 
PMERRINVFACENAME 

PMERRINVFACENAMEDESC 
PMERRJNVHPS 
PMERRPSBUSY 


An attempt was made to create a font that was not loaded. 

An invalid font family name was passed to 
GpiQueryFaceString. 

The font facename description is invalid. 

An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 
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GpiQueryFaceString - 
Query Face String 


Remarks 

This function generates a compound face name (for example, “Courier Bold Italic") from a family 
name (for example, “Courier"). 

The compound face name can be used on a GpiCreateLogFont function. 

Example Code 

This example uses GpiQueryFaceString to generates a compound face name of 'Courier Light Italic' 
from the family name 'Courier.' 


Idefine INCL_GPILCIDS /* Font functions */ 
linclude <os2.h> 

ULONG cbRetLength; /* length of compound face name */ 
HPS hps; /* Presentation-space handle */ 
char pszFamilyName[13] ;/* Family name */ 
FACENAMEDESC pfndFaceAttrs; /* Face-name description */ 
LONG 1 Length; /* length of buffer */ 
char *pszCompoundFaceName;/* Compound face name */ 


/* family name is 'Courier 1 */ 
strcpy (pszFami 1 yName , "Couri er" ) ; 

/* let the function determine the buffer length and return it */ 

1 Length = 0L; 

/* initialize face name description structure for Light weight 
class, normal width, and italics */ 
pfndFaceAttrs. usSize = sizeof (FACENAMEDESC) ; 

/* Length of structure */ 

pfndFaceAttrs. usWeightCl ass = FWEIGHT_LIGHT; /* Weight class */ 

pfndFaceAttrs. usWidthClass = FWIDTH_NORMAL; /* Width class */ 

pfndFaceAttrs. usReserved = 0; /* Reserved */ 

pfndFaceAttrs.fi Options = FTYPE_ITALIC; 

/* Other characteristics of the font */ 

cbRetLength = GpiQueryFaceString (hps, pszFami lyName, 

&pfndFaceAttrs, 1 Length, 
pszCompoundFaceName) ; 
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GpiQueryFontAction - 
Query Font Action 


^define INCL_GPILCIDS /* Or use INCL_GPI or INCL_PM */ 


ULONG GpiQueryFontAction (HAB hab, ULONG flOptlons) 


This function determines whether available fonts have been affected since the last time the function 
was called. 

Parameters 

hab (HAB) - input 

Anchor-block handle. 

flOptlons (ULONG) - input 
Options 

The following may be OR’ed together if required: 

QFA_PUBLIC Interested in any change of public fonts. 

QFA_PRIVATE Interested in any change of private fonts for the current process. 

Returns 

Actions indicator: 

If no error occurs, QFA_PUBLIC and QFA_PRIVATE may be OR’ed together. 

QFA_PUBLIC A change of public fonts has occurred. 

QFA PRIVATE A change of private fonts affecting the current process has occurred. 
QFA_ERROR Error occurred. 

Possible returns from WinGetLastError 

PMERR INV OR INCOMPAT OPTIONS An invalid or incompatible (with micro presentation 

space) options parameter was specified with 
GpiCreatePS or GpiSetPS. 


Remarks 

This function can be used by a font selection dialog to find out whether its database of font 
information is still valid. 

The function returns that both public and private font changes have taken place the first time it is 
called on a given process. 
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GpiQueryFontFileDescriptions - 
Query Font File Descriptions 


#define INCL_GPILCIDS /* Or use INCL_GPI or INCL_PM */ 


LONG GpiQueryFontFileDescriptions (HAB hab, PSZ pszFHename, PLONG pICount, 

PFFDESCS affdescsNames) 


This function determines whether a given file is a font resource file, and if so, returns the family and 
face names of the fonts that it contains. 

Parameters 

hab (HAB) - input 

Anchor-block handle. 

pszFHename (PSZ) - input 
Fully qualified filename. 

This is the name of the font resource. The filename extension is .FON. 

pICount (PLONG) - input/output 

Maximum number of family and face name pairs to be returned. 

The number of pairs of descriptions that are actually returned in affdescsNames is returned in 
this variable. 

affdescsNames (PFFDESCS) - output 
Array of font file descriptors. 

An array of 2* pICount consecutive 32-byte fields, in which the family and face names of each 
font, in turn, are returned alternately. For each pair, the family name is returned first. 


Returns 

Returns: 

>0 Number of fonts for which details were not returned 

GPI_ALTERROR Error. 

Possible returns from WinGetLastError 

PMERR_INV_FONT_FILE_DAT A 

PMERR_INV_LENGTH_OR_COUNT 

Remarks 

Details are returned for as many fonts as can be held in affdescsNames. 

By inspecting the returned data, the application can tell whether a particular font resource file 
contains the fonts it requires, before loading it. 

By specifying pICount as 0, and then looking at the value returned in IRemFonts, an application can 
determine how many fonts there are in the file, and then allocate the correct amount of buffer space 
for a subsequent call to obtain all of the names. 


The font file specified with GpiLoadFonts, 
GpiLoadPublicFonts, 

An invalid length or count parameter was specified. 
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GpiQueryFontFileDescriptions 
Query Font File Descriptions 


Example Code 

This example uses the GpiQueryFontFileDescriptions to retrieve the typeface family and names for 
the fonts in the helv.dll file. The function is called twice, once to determine the actual number of 
fonts in the file, and again to retrieve the descriptions. 


Idefine INCL_GPILCIDS /* Font functions */ 
Idefine INCL_D0SMEMMGR /* DOS Memory Manager Functions */ 
linclude <os2.h> 

HPS hps; /* presentation space handle */ 
HAB hab; /* anchor-block handle */ 
PFFDESCS pffdescs; /* array of font file descriptors */ 
LONG cFonts =0; /* number of descriptions not returned */ 


/* Retrieve a count of all fonts in the file. */ 

cFonts = GpiQueryFontFileDescriptions(hab, "helv", ScFonts, NULL); 

/* Allocate space for the descriptions. */ 

DosAllocMem((VOID *) pffdescs, (ULONG) (cFonts*sizeof(FFDESCS)) , 
PAG_C0MMIT | PAG_READ | PAGJIRITE); 

/* Retrieve the descriptions. */ 

GpiQueryFontFileDescriptions(hab, "helv", ScFonts, pffdescs); 
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GpiQueryFontMetrics - 
Query Font Metrics 


#define INCL_GPILCIDS /* Or use INCL_GPI or INCL_PM 7 


BOOL GpiQueryFontMetrics (HPS hps, LONG IMetrlcsLength, PFONTMETRICS pfmMetrlcs) 


This function returns a record providing details of the font metrics for the logical font that is currently 
selected. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

IMetrlcsLength (LONG) - input 
Length of metrics. 

pfmMetrlcs (PFONTMETRICS) - output 
Metrics of font. 

In this buffer are returned the font metrics of the logical font, identified by the current value of 
the character set attribute. 

No more data than IMetricsLength is returned. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid length or count parameter was specified. 

An internal coordinate overflow error occurred. This can 
occur if coordinates or matrix transformation elements (or 
both) are invalid or too large. 


PMERR_INV_HPS 

PMERR_PS_BUSY 

PMERR_INV_LENGTH_OR_COUNT 

PMERRCOORDINATEOVERFLOW 


Remarks 

All sizes are returned in world coordinates. 

An application can determine if the font szFacename\_FACESIZE2 (as returned in pfmMetrics ) has 
been truncated by checking the usType field in pfmMetrics for the FM_TYPE_FACETRUNC indicator. 
If the face name has been truncated, this bit will be set, and the application can issue a 
WinQueryAtomName function, passing in the FaceNameAtom (as returned in pfmMetrics) to retrieve 
the full face name from the System Atom table. 
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GpiQueryFontMetrics - 
Query Font Metrics 

Example Code 

This example uses the GpiQueryFontMetrics function to retrieve the font metrics for the current font. 

Idefine INCL_GPILCIDS /* Font functions */ 

linclude <os2.h> 

HPS hps; /* presentation space handle */ 

FONTMETRICS fm; /* metrics structure */ 

GpiQueryFontMetrics (hps, si zeof (FONTMETRICS) , &fm); 
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GpiQueryFonts - 
Query Fonts 

#define INCL_GPILCIDS /* Or use INCL_GPI or INCL_PM 7 


LONG GpiQueryFonts (HPS hps, ULONG flOptlons, PSZ pszFacename, PLONG pIReqFonts, 
LONG IMetrlcsLength, PFONTMETRICS afmMetrics) 


This function returns a record providing details of the fonts that match the specified pszFacename. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

flOptlons (ULONG) - input 
Enumeration options. 

This controls which fonts are to be enumerated. If both the following options are required, the 
values should be ORed together: 

QF PUBLIC Enumerate public fonts. 

QFPRIVATE Enumerate private fonts. 

QF_NO_DEVICE Device fonts are not reported. 

QF_NO_GENERIC Generic fonts are not reported. 

pszFacename (PSZ) - input 
Face name of fonts. 

If the pointer to pszFacename is NULL, all available fonts are queried, regardless of their face 
names. 

pIReqFonts (PLONG) - input/output 
Count of fonts. 

The number of fonts for which the application requires the metrics. This variable returns the 
number of fonts returned. 

IMetrlcsLength (LONG) - input 
Length of metrics. 

The length of each metrics record to be returned. The afmMetrics data area must be pIReqFonts 
multiplied by IMetricsLength long. 

afmMetrics (PFONTMETRICS) - output 
Metrics of font. 

In this structure are returned the font metrics of up to pIReqFonts matching fonts. The format for 
each record is as defined for GpiQueryFontMetrics, except that the usCodePage field has no 
meaning in this context, and is indeterminate. For each font, no more data than IMetricsLength 
is returned. 

Returns 

Count of fonts not returned: 

>0 Count of fonts not returned 

GPI_ALTERROR Error. 

Possible returns from WinGetLastError 

PMERR INV HPS An invalid presentation-space handle was specified. 
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GpiQueryFonts 
Query Fonts 


PMERR_PS_BUSY 
P M E R R_IN V_LENGTH_OR_COU N T 


An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid length or count parameter was specified. 


PMERR_COORDINATE_OVERFLOW An internal coordinate overflow error occurred. This can 

occur if coordinates or matrix transformation elements (or 
both) are invalid or too large. 


Remarks 

Font metrics are returned for as many matching fonts as can be held in afmMetrics. 

By inspecting the returned data, the application can choose which of the available fonts is most 
appropriate for its requirements. If necessary, it can force selection of a particular font, by 
specifying its match (as returned in afmMetrics) in the pAttrs structure for GpiCreateLogFont, 
however, this is only valid for a particular device/device driver combination on a single machine. 

This method should be avoided as a method for selecting a font. 

An application can determine if the font szFacename[FACESiZE ] (as returned in afmMetrics ) has 
been truncated by checking the usType field in afmMetrics for the FM_TYPE_FACETRUNC indicator. 

If the face name has been truncated, this bit will be set, and the application can issue a 
WinQueryAtomName function, passing in the FaceNameAtom (as returned in afmMetrics) to retrieve 
the full face name from the System Atom table. 

By specifying pIReqFonts asO, and then looking at the value returned in IRemFonts, an application 
can determine how many fonts there are that match the pszFacename. 

All sizes are returned in world coordinates. 

Example Code 

This example uses the GpiQueryFonts function to retrieve the font metrics for all private fonts having 
the "Helv" typeface name. The function is called twice, first to determine the number of fonts 
available, and then again to retrieve the font metrics for all the fonts. 


Idefine INCL_GPILCIDS /* Font functions */ 
Idefine INCL_DOSMEMMGR /* DOS Memory Manager Functions */ 
linclude <os2.h> 

HPS hps; /* presentation space handle */ 
LONG cFonts; /* fonts not returned */ 
LONG ITemp = 0L; /* font count */ 
PFONTMETRICS pfm; /* metrics structure */ 


/* Determine the number of fonts. */ 

cFonts = GpiQueryFonts (hps, QF_PRIVATE, "Helv", &lTemp, 
(LONG) sizeof (FONTMETRICS) , NULL); 

/* Allocate space for the font metrics. */ 

DosAllocMem((VOID *)pfm, (ULONG) (cFonts*sizeof(FONTMETRICS)) , 
PAG_COMMIT | PAG_READ | PAG_WRITE) ; 

/* Retrieve the font metrics. */ 

cFonts = GpiQueryFonts (hps, QF_PRIVATE, "Helv", ScFonts, 
(LONG) sizeof (FONTMETRICS), pfm); 
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GpiQueryFullFontFileDescriptions - 
Query Full Font File Descriptions 


#define INCL_GPILCIDS /* Or use INCL_GPI or INCL_PM */ 


LONG GpIQueryFullFontFlleDescrlptlons (HAB hab, PSZ pszFllename, PLONG piCount, 

PVOID pNames, PLONG piNamesBuffLength) 


This function determines whether a given file is a font resource file, and if so, returns the family and 
face names of the fonts that it contains. 

Parameters 

hab (HAB) - input 

Anchor-block handle. 

pszFllename (PSZ) - input 
Fully qualified filename. 

This is the name of the font resource. 

piCount (PLONG) - input/output 

Maximum number of family and face name pairs to be returned. 

The number of pairs of descriptions that are actually returned in pNames is returned in this 
variable. 

pNames (PVOID) - output 
Font file descriptors. 

A buffer in which the font file family and face name pairs are returned. They are each returned 
in a FFDESCS2 structure, with successive structures packed end to end. 

piNamesBuffLength (PLONG) - input/output 
Length, in bytes, of the pNames data buffer. 

On return, this is set to the actual length needed to hold all of the fami ly names and face names 
in the file. 

Returns 

Returns: 

>0 Number of fonts for which details were not returned 

GPI_ALTERROR Error. 

Possible returns from WinGetLastError 

PMERR_INV_FONT_FILE_DATA 

PMERR_INV_LENGTH_OR_COUNT 

Remarks 

Details are returned for as many fonts as can be held in pNames. 

By inspecting the returned data, the application can tell whether a particular font resource file 
contains the fonts it requires, before loading it. 

By specifying pNames as NULL, and then looking at the value returned in piNamesBuffLength, an 
application can determine the length of the buffer needed to hold all of the font names. 

Support for this function is device dependent. 


The font file specified with GpiLoadFonts, 
GpiLoadPublicFonts, 

An invalid length or count parameter was specified. 
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GpiQueryFullFontFileDescriptions 
Query Full Font File Descriptions 


Example Code 

/* This example uses the GpiQueryFullFontFileDescriptions to */ 
/* retrieve the typeface family and names for the fonts in the */ 
/* helv.dll file. The function is called twice, once to */ 

/* determine the actual number of fonts in the file, and again */ 
/* to retrieve the descriptions. */ 

PFFDESCS pffdescs; 

SEL sel ; 

LONG cFonts = 0; 

LONG lBuflen = 0; 


/* Retrieve a count of all fonts in the file. */ 

cFonts = GpiQueryFontFileDescriptions(hab, "helv", 

ScFonts, NULL, SlBuflen) 

/* Allocate space for the descriptions. */ 

DosAl 1 ocSeg( (USHORT) lBuflen, &sel, SEG_N0NSHARED) ; 
pffdescs = MAKEP(sel, 0); 


/* Retrieve the descriptions. */ 

GpiQueryFullFontFileDescriptions(hab, "helv", &cFonts, 
pffdescs, SlBuflen); 
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GpiQueryGraphicsField - 
Query Graphics Field 


#define INCL_GPITRANSFORMS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiQueryGraphicsField (HPS hps, PRECTL prcIFIeld) 


This function returns the bottom-left and top-right corners of the graphics field in presentation page 
units, as set by the GpiSetGraphicsField function. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

prcIFIeld (PRECTL) - output 
Graphics field. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERR INV HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

Example Code 

This example uses GpiQueryGraphicsField to return the bottom-left and top-right corners of the 
graphics field in presentation page units, as set by the GpiSetGraphicsField call, and then assigns 
the x coordinate of the lower left hand field corner to a variable. 


Idefine INCL_GPITRANSFORMS /* Transform functions */ 
#inc1ude <os2.h> 

BOOL f Success; /* success indicator */ 
HPS hps; /* Presentation-space handle */ 
RECTL prcl Field; /* graphics field */ 
LONG lLwrLftxCoord; /* lower left x coordinate of field */ 


fSuccess = GpiQueryGraphicsField(hps, &prcl Fi eld) ; 

/* if successful, assign lower left x coordinate of graphics field */ 
if (fSuccess == TRUE) 

lLwrLftxCoord = prclField.xLeft; 
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GpiQuerylnitialSegmentAttrs - 
Query Initial Segment Attributes 


#define INCL_GPISEGMENTS /* Or use INCL_GPI or INCL_PM */ 

LONG GpiQuerylnitialSegmentAttrs (HPS hps, LONG lAttribute) 

This function returns the current value of a particular initial segment attribute. 

Parameters 

bps (HPS) - input 

Presentation-space handle. 

lAttribute (LONG) - input 
Attribute to be queried. 

Identifies the attribute to be returned by this function: 

ATTRDETECT ABLE Detectability 

ATTRVISIBLE Visibility 

ATTRCHAINED Chained 

ATTR_DYNAMIC Dynamic 

ATTR_FASTCHAIN Fast chaining 

ATTR_PROP_DETECTABLE Propagate detectability 
ATTR_PROP_VISIBLE Propagate visibility. 

Returns 

Current initial attribute value: 

ATTR_ON On/yes 

ATTR_OFF Off/no 

ATTRERROR Error. 

Possible returns from WinGetLastError 

PMERR JNVHPS 
PMERRPSBUSY 

PMERRJNV_SEG_ATTR 

PMERRINVMICROPSFUNCTION 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid attribute parameter was specified with 
GpiSetSegmentAttrs, GpiQuerySegmentAttrs, 
GpiSetlnitialSegmentAttrs, or 
GpiQuerylnitialSegmentAttrs. 

An attempt was made to issue a function that is invalid in 
a micro presentation space. 


Remarks 

Initial segment attributes are modal settings used to determine the initial attributes of new segments 
as those new segments are created; see GpiSetlnitialSegmentAttrs. 
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GpiQuerylnitialSegmentAttrs - 
Query Initial Segment Attributes 


Example Code 

This example uses GpiQuerylnitialSegmentAttrs to queries the current state of the dynamic segment 
attribute. 


Idefine INCL_GPISEGMENTS /* Segment functions */ 
linclude <os2.h> 

LONG lvalue; /* current element pointer */ 
HPS hps; /* Presentation-space handle */ 
LONG 1 Attribute; /* attribute to query */ 


/* query the dynamic attribute */ 
lAttribute = ATTR_DYNAMIC; 

lValue = GpiQueryInitialSegmentAttrs(hps, lAttribute); 
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GpiQueryKerningPairs 
Query Kerning Pairs 


^define INCL_GPILCIDS /* Or use INCL_GPI or INCL_PM 7 


LONG GpiQueryKerningPairs (HPS hps, LONG ICount, PKERNINGPAIRS akrnprData) 


This function returns kerning pair information for the logical font identified by the current value of the 
character set attribute. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

ICount (LONG) - input 

Number of elements in akrnprData. 

akrnprData (PKERNINGPAIRS) - output 
Kerning pairs. 

An array of ICount kerning pairs in which information is returned. No more than ICount records 
are returned. 

Returns 

Number returned and error indicators: 

>0 Number of kerning pairs returned 

GPI_ALTERROR Error. 

Possible returns from WinGetLastError 

PMERRJNVHPS 
PMERRPSBUSY 

PMERRJNVLENGTHORCOUNT 
PMERRCOORDINATEOVERFLOW 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid length or count parameter was specified. 

An internal coordinate overflow error occurred. This can 
occur if coordinates or matrix transformation elements (or 
both) are invalid or too large. 


Remarks 

The number of kerned pairs is a field in the font metrics. 
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GpiQueryKerningPairs - 
Query Kerning Pairs 


Example Code 

This example uses the GpiQueryKerningPairs function to retrieve the kerning information for the 
current font. 


Idefine INCL_GPILCIDS /* Font functions */ 
Idefine INCL_DOSMEMMGR /* DOS Memory Manager Functions */ 
linclude <os2.h> 

HPS hps; /* presentation space handle */ 
FONTMETRICS fm; /‘metrics structure */ 
PKERNINGPAIRS akrnpr; /‘kerning pairs array */ 


GpiQueryFontMetrics(hps, (LONG) sizeof (FONTMETRICS), &fm); 

DosAllocMem((VOID *)akrnpr, 

(ULONG)(fm.sKerningPairs * sizeof (KERNINGPAIRS)) , 
PAG_COMMIT | PAG_READ | PAG_WRITE) ; 

GpiQueryKerningPairs (hps, (LONG) fm.sKerningPairs, akrnpr); 
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GpiQueryLineEnd 
Query Line End 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


LONG GpiQueryLineEnd (HPS hps) 


This function returns the current line-end attribute. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 


Returns 

Line end: 

LINEEND_DEFAULT Default 
>0 Line end 

LINEEND_ERROR Error. 

Possible returns from WinGetLastError 

PMERRJNVHPS 

PMERR_PS_BUSY 

PMERRINVINRETAINMODE 

P M E R R_IN V_DC_TYPE 


Remarks 

This function is invalid when the drawing 

Example Code 

This example uses GpiQueryLineEnd to return the current line-end attribute after setting the draw 
mode to DRAW. 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An attempt was made to issue a function (for example, 
query) that is invalid when the actual drawing mode is not 

draw or draw-and-retaln. 

An invalid type parameter was specified with 
DevOpenDC, or a function was issued that is invalid for a 
OD_METAFILE_NOQUERY device context. 


mode (see GpiSetDrawingMode) is set to retain. 


Idefine INCL_GPIPRIMITIVES /* Primitive functions */ 
Idefine INCL_GPICONTROL /* Control functions */ 
linclude <os2.h> 


HPS hps; /* Presentation-space handle 

LONG 1 LineEnd; /* Line end 

if (Gpi SetDrawi ngMode ( hps , DM_DRAW) == TRUE) 

1 LineEnd = GpiQueryLineEnd(hps) ; 


*/ 

*/ 
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GpiQueryLineJoin - 
Query Line Join 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


LONG GpiQueryLineJoin (HPS hps) 


This function returns the current line-join attribute, as set by the GpiSetLineJoin function. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 


Returns 

Line join: 

LINEJOIN_DEFAULT Default 
>0 Line join 

LINEJOIN_ERROR Error. 

Possible returns from WinGetLastError 

PMERR_INV_HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_IN_RETAIN_MODE An attempt was made to issue a function (for example, 

query) that is invalid when the actual drawing mode is not 

draw or draw-and-retain. 

PMERR_INV_DC_TYPE An invalid type parameter was specified with 

DevOpenDC, or a function was issued that is invalid for a 
OD_METAFILE_NOQUERY device context. 

Remarks 

This function is invalid when the drawing mode (see GpiSetDrawingMode) is set to retain. 

Example Code 

This example uses GpiQueryLineJoin to return the current line-join attribute after setting the draw 
mode to DRAW. 


Idefine INCL_GPIPRIMITIVES /* Primitive functions */ 
Idefine INCL_GPIC0NTR0L /* Control functions */ 
linclude <os2.h> 


HPS hps; /* Presentation-space handle 

LONG ILineJoin; /* Line join 

if (GpiSetDrawingMode (hps, DM_DRAW) == TRUE) 
ILineJoin = GpiQueryLineJoin(hps) ; 


*/ 

*/ 
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GpiQuery Line! ype 
Query Line Type 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


LONG GpiQueryLineType (HPS hps) 


This function returns the current cosmetic line-type attribute, as set by the GpiSetLineType function. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

Returns 

Line type: 

LINETYPE_DEFAULT Default 
>0 Line type 

LINETYPE_ERROR Error. 

Possible returns from WinGetLastError 

PMERR_INV_HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_IN_RETAIN_MODE An attempt was made to issue a function (for example, 

query) that is invalid when the actual drawing mode is not 

draw or draw-and-retain. 

PMERR_INV_DC_TYPE An invalid type parameter was specified with 

DevOpenDC, or a function was issued that is invalid for a 
OD_METAFILE_NOQUERY device context. 

Remarks 

This function is invalid when the drawing mode (see GpiSetDrawingMode) is set to retain. 

Example Code 

This example uses GpiQueryLineType to return the current cosmetic line-type attribute after setting 
the draw mode to DRAW. 


Idefine INCL_GPI PRIMITIVES /* Primitive functions */ 
Idefine INCL_GPICONTROL /* Control functions */ 
linclude <os2.h> 

HPS hps; /* Presentation-space handle */ 
LONG ILineType; /* Line type */ 


if (GpiSetDrawingMode (hps, DM_DRAW) == TRUE) 
ILineType = GpiQueryLineType(hps) ; 
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GpiQueryLineWidth - 
Query Line Width 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


FIXED GpiQueryLineWidth (HPS hps) 


This function returns the current value of the cosmetic line-width attribute, as set by the 
GpiSetLineWidth function. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 


Returns 

Line width: 

LINEWIDTH_DEFAULT Default 
>0 Line width 

LINEWIDTH_ERROR Error. 

Possible returns from WinGetLastError 

PMERR_INV_HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_IN_RETAIN_MODE An attempt was made to issue a function (for example, 

query) that is invalid when the actual drawing mode is not 

draw or draw-and-retaln. 

PMERR_INV_DC_TYPE An invalid type parameter was specified with 

DevOpenDC, or a function was issued that is invalid for a 
OD_METAFILE_NOQUERY device context. 

Remarks 

This function is invalid when the drawing mode (see GpiSetDrawingMode) is set to retain. 

Example Code 

This example uses GpiQueryLineWidth to return the current cosmetic line-width attribute after 
setting the draw mode to DRAW. 


Idefine INCL_GPI PRIMITIVES /* Primitive functions */ 
Idefine INCL_GPICONTROL /* Control functions */ 
linclude <os2.h> 

HPS hps; /* Presentation-space handle */ 
FIXED fxLineWidth; /* Line width */ 


if (GpiSetDrawingMode(hps, DM_DRAW) == TRUE) 
fxLineWidth = GpiQueryLineWidth(hps) ; 
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GpiQueryLineWidthGeom 
Query Line Width Geom 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


LONG GpiQueryLineWidthGeom (HPS hps) 


This function returns the current geometric line-width attribute, as set by the GpiSetLineWidthGeom 
function. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 


Returns 

Geometric line width: 

If the geometric line width is currently set to the default, zero is returned. 
>0 Geometric line width 

LINEWIDTHGEOMERROR Error. 


Possible returns from WinGetLastError 

PMERR_INV_HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_IN_RETAIN_MODE An attempt was made to issue a function (for example, 

query) that is invalid when the actual drawing mode is not 

draw or draw-and-retain. 

PMERR_INV_DC_TYPE An invalid type parameter was specified with 

DevOpenDC, or a function was issued that is invalid for a 
OD_METAFILE_NOQUERY device context. 


Remarks 

This function is invalid when the drawing mode (see GpiSetDrawingMode) is set to retain. 


Example Code 

This example uses GpiQueryLineWidthGeom to return the current geometric line-width attribute 
after setting the draw mode to DRAW. 


Idefine INCL_GPIPRIMITIVES /* Primitive functions */ 
Idefine INCL_GPICONTROL /* Control functions */ 
#include <os2.h> 

HPS hps; /* Presentation-space handle */ 
LONG ILineWidth; /* geometric line width */ 


if (GpiSetDrawingMode(hps, DM_DRAW) == TRUE) 
ILineWidth = GpiQueryLineWidthGeom(hps) ; 
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GpiQueryLogColorTable - 
Query Logical Color Table 


#define INCL_GPILOGCOLORTABLE /* Or use INCL_GPI or INCL_PM */ 


LONG GpiQueryLogColorTable (HPS bps, ULONG fiOptlons, LONG IStart, LONG ICount, 

PLONG alArray) 


This function returns the logical color table. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

fiOptlons (ULONG) - input 
Specifies options: 

LCOLOPTJN DEX 

BT The index is to be returned for each RGB value 
Other flags are reserved and must be B‘0’. 

IStart (LONG) - input 

Starting index for which data is to be returned. This must be greater than or equal to zero. 

ICount (LONG) - input 
Count of elements. 

Number of elements available in alArray. 

alArray (PLONG) - output 

Array in which the information is returned. 

If the LCOLOPTJNDEX flag is B‘0’, it is an array of RGB values (each value is as defined for 
GpiCreateLogColorTable), starting with the specified index, and ending either when there are no 
further loaded entries in the table, or when alArray has been exhausted. If the logical color 
table is not loaded with a contiguous set of indexes, QLCT_NOTLOADED is returned as the RGB 
value for any index values, outside the default range, that have not been explicitly loaded. 

If the LCOLOPTJNDEX flag is BT, it is an array of alternating color indexes and RGB values, in 
the order indexl, RGB valuel, index2, RGB value2,... An even number of elements is always 
returned. If the logical color table is not loaded with a contiguous set of indexes, any index 
values that are not loaded are skipped. 


Returns 

Number of elements returned and error indicators: 
QLCT_RGB Table in RGB mode, no elements returned 
>0 Number of elements returned 

QLCT_ERROR Error. 

Possible returns from WinGetLastError 

PMERRINVHPS 
PMERRPSBUSY 

PMERRJNV_LENGTH_OR_COUNT 
PMERR INV_COLOR_OPTIONS 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid length or count parameter was specified. 

An invalid options parameter was specified with a logical 
color table or color query function. 
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GpiQueryLogColorTable - 
Query Logical Color Table 


PMERR_INV_COLOR_ST ART INDEX An invalid starting index parameter was specified with 

logical color table or color query function. 

PMERR_PALETTE_SELECTED Color palette operations cannot be performed on a 

presentation space while a palette is selected. 


Example Code 

This example uses the GpiQueryLogColorTable function to retrieve all the entries in the current 
logical color table. 


Idefine INCL_GPILOGCOLORTABLE /* Color Table functions */ 
Idefine INCL_DOSMEMMGR /* DOS Memory Manager Functions */ 
Idefine INCL_DEV /* Device Function definitions */ 
linclude <os2.h> 

HPS hps; /* presentation space handle */ 
LONG cColors; /* number of colors */ 
PLONG alColor; /* color table array */ 


/* Find out how many colors are in the color table. */ 

DevQueryCaps(GpiQueryDevice(hps) , CAPS_C0L0RS, 1L, ScColors); 

/* Allocate space for the color values and indexes. */ 

DosAllocMem((VOID *)alColor, (UL0NG)cColors*2, 

PAG_COMMIT | PAG_READ | PAG_WRITE) ; 

/* Retrieve the values. */ 


GpiQueryLogColorTable(hps, /* presentation space */ 

LC0L0PT_INDEX, /* retrieve indexes and RGB values */ 

OL, /* start with first entry */ 

cColors * 2, /* copy 2 values for each entry */ 

alColor); /* array to receive values */ 
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GpiQueryLogicalFont - 
Query Logical Font 


#define INCL_GPILCIDS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiQueryLogicalFont (HRS hps, LONG ILcId, PSTR8 pName, PFATTRS pfatAttrs, 

LONG lAttrsLength) 


This function returns the description of a logical font. See GpiCreateLogFont. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

ILcId (LONG) - input 
Local identifier. 

Logical font local identifier, in the range 0 through 254. Specify 0 to query the default font. 

pName (PSTR8) - output 
Logical font name. 

An 8-character name for the logical font. 

pfatAttrs (PFATTRS) - output 
Attributes of font. 

lAttrsLength (LONG) - input 
Length of pfatAttrs buffer. 

The maximum length of font attribute data to be returned. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 


PMERRJNVHPS 

PMERRPSBUSY 

PMERR_INV_SETID 

PMERRSETIDINUSE 

PMERR_INV_LENGTH_OR_COUNT 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid setid parameter was specified. 

An attempt was made to specify a setid that was already 
in use as the currently selected character, marker or 
pattern set. 

An invalid length or count parameter was specified. 


Remarks 

If the specified local identifier is in use to tag a bit map (see GpiSetBitmapId), an error is raised. 
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GpiQueryLogicalFont 
Query Logical Font 


Example Code 

This example uses GpiQueryLogicalFont to return the description of the default logical font and if the 
query succeeds, assigns the font code page to a variable. 


Idefine INCL_GPILCIDS /* Font functions 

linclude <os2.h> 


BOOL f Success; /* 
HPS hps; /* 
LONG ILcid; /* 
PSTR8 pName; /* 
PFATTRS pfatAttrs; /* 
LONG lAttrs Length; /* 


USHORT usFontCodePage; /* 

/* query the default font 
ILcid = 0L; 


success indicator 
Presentation-space handle 
local identifier 
8 character logical font name 
Attributes of font 
length of buffer 
font code page 

V 


*/ 


*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 


/* return all information */ 
lAttrsLength = sizeof(FATTRS) ; 

fSuccess = GpiQueryLogi cal Font (hps, ILcid, pName, pfatAttrs, 

lAttrsLength) ; 


/* if successful, assign value of font code page */ 
if (fSuccess == TRUE) 

usFontCodePage = pfatAttrs->usCodePage; 
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GpiQueryMarker - 
Query Marker 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


LONG GpiQueryMarker (HPS hps) 


This function returns the current value of the marker symbol attribute, as set by the GpiSetMarker 
function. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 


Returns 

Marker symbol: 

MARKSYM_DEFAULT Default 
>0 Marker symbol 

MARKSYM_ERROR Error. 

Possible returns from WinGetLastError 

PMERRINVHPS 
PMERRPSBUSY 

PMERRINVINRETAINMODE 

PMERR_INV_DC_TYPE 

Remarks 

This function is invalid when the drawing 

Example Code 

This example uses GpiQueryMarker to return the current marker symbol attribute after setting the 
draw mode to DRAW. 


Idefine INCL_GPIPRIMITIVES /* Primitive functions */ 
Idefine INCL_GPICONTROL /* Control functions */ 
linclude <os2.h> 

HPS hps; /* Presentation-space handle */ 
LONG 1 Symbol ; /* marker symbol */ 


if (GpiSetDrawingMode(hps, DMDRAW) == TRUE) 
1 Symbol = GpiQueryMarker (hps) ; 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An attempt was made to issue a function (for example, 
query) that is invalid when the actual drawing mode is not 

draw or draw-and-retain. 

An invalid type parameter was specified with 
DevOpenDC, or a function was issued that is invalid for a 
OD_METAFILE_NOQUERY device context. 


mode (see GpiSetDrawingMode) is set to retain. 
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GpiQueryMarkerBox 
Query Marker Box 


#define INCLGPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiQueryMarkerBox (HPS hps, PSIZEF psizfxSize) 


This function returns the current value of the marker-box attribute, as set by the GpiSetMarkerBox 
function. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

psizfxSize (PSIZEF) - output 
Size of marker box. 

The size of the marker box is in world coordinates. 

If the marker box is currently set to the default, the default size is returned. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An attempt was made to issue a function (for example, 
query) that is invalid when the actual drawing mode is not 

draw or draw-and-retain. 

An invalid type parameter was specified with 
DevOpenDC, or a function was issued that is invalid for a 
OD_METAFILE_NOQUERY device context. 


Possible returns from WinGetLastError 

PMERR_INV_HPS 

PMERR_PS_BUSY 

PMERRJNVJN RETAIN MODE 

P M E R RJN V_DC_TYPE 


Remarks 

This function is invalid when the drawing mode (see GpiSetDrawingMode) is set to retain. 
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GpiQueryMarkerBox - 
Query Marker Box 


Example Code 

This example uses GpiQueryMarkerBox to return the current marker-box attribute after setting the 
draw mode to DRAW. 


Idefine INCL_GPIPRIMITIVES /* Primitive functions */ 
Idefine INCL_GPICONTROL /* Control functions */ 
linclude <os2.h> 

BOOL fSuccess; /* success indicator */ 
HPS hps; /* Presentation-space handle */ 
SIZEF psizfxSize; /* size of marker-box */ 
FIXED 1 Width; /* marker-box width */ 


if (GpiSetDrawingMode(hps, DM DRAW) == TRUE) 

fSuccess = GpiQueryMarkerBox(hps, &psi zf xSi ze) ; 

/* if successful, assign value of marker-box width */ 
if (fSuccess == TRUE) 
lWidth = psizfxSize. cx; 


Chapter 5. Graphics Functions 


5-319 



GpiQueryMarkerSet 
Query Marker Set 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


LONG GpiQueryMarkerSet (HPS hps) 


This function returns the current value of the marker-set attribute, as set by the GpiSetMarkerSet 
function. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 


Returns 

Marker-set local 

LCID_DEFAULT 

>0 

LCIDERROR 


identifier: 

Default 

Marker-set local identifier 
Error. 


Possible returns from WinGetLastError 

PMERRJNV_HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_IN_RETAIN_MODE An attempt was made to issue a function (for example, 

query) that is invalid when the actual drawing mode is not 

draw or draw-and-retaln. 

PMERR_INV_DC_TYPE An invalid type parameter was specified with 

DevOpenDC, or a function was issued that is invalid for a 
OD_METAFILE_NOQUERY device context. 


Remarks 

This function is invalid when the drawing mode (see GpiSetDrawingMode) is set to retain. 

Example Code 

This example uses GpiQueryMarkerSet to return the current marker-set attribute after setting the 
draw mode to DRAW. 


Idefine INCL_GPIPRIMITIVES /* Primitive functions */ 
Idefine INCL_GPICONTROL /* Control functions */ 
finclude <os2.h> 

HPS hps; /* Presentation-space handle */ 
LONG lSet; /* marker-set local identifier */ 


if (GpiSetDrawingMode(hps, DM_DRAW) == TRUE) 
lSet = GpiQueryMarkerSet (hps) ; 
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GpiQueryMetaFileBits - 
Query Metafile Bits 


#define INCL_GPIMETAFILES /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiQueryMetaFileBits (HMF hmf, LONG lOffset, LONG ILength, PBYTE pbData) 


This function transfers a metafile to application storage. 


Parameters 

hmf (HMF) - input 

Memory-metafile handle. 

lOffset (LONG) - input 
Byte offset. 

Offset into the metafile data from which the transfer must start. This is useful in instances where 
the metafile data is too long to fit into a single application buffer. 

ILength (LONG) - input 

Length in bytes of the metafile data to copy. 

pbData (PBYTE) - output 
Metafile data. 

Address in application storage into which the metafile data is copied. 

Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRINVHMF 
PMERRJNVMET AFILELENGTH 

PMERR_INV_METAFILE_OFFSET 

PMERRMET AFILE _IN_USE 

PMERR_TOO_M ANY_MET AFILESINUSE 


An invalid metafile handle was specified. 

An invalid length parameter was specified with 
GpiSetMetaFileBits or GpiQueryMetaFileBits. 

An invalid length parameter was specified with 
GpiSetMetaFileBits or GpiQueryMetaFileBits. 

An attempt has been made to access a metafile that is in 
use by another thread. 

The maximum number of metafiles allowed for a given 
process was exceeded. 


Remarks 

The total length of a metafile can be found from the data returned by GpiQueryMetaFileLength. This 
function allows an application to retrieve the data in units of a manageable size. 
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GpiQueryMetaFileBits 
Query Metafile Bits 


Example Code 

This example uses the GpiQueryMetaFileBits function to retrieve the graphics-order data from the 
specified metafile. The GpiQueryMetaFileLength function returns the length of the metafile. 


Idefine I NCL_GP IMETAFI LES /* Metafile functions */ 
Idefine INCL_DOSMEMMGR /* DOS Memory Manager Functions */ 
linclude <os2.h> 

HPS hps; /* presentation space handle */ 
HMF hmf; /* metafile handle */ 
LONG cBytes; /* metafile length */ 
LONG off; /* metafile byte offset */ 
PBYTE pbBuffer; /* metafile data buffer */ 


hmf = GpiLoadMetaFile(hps, "sample. met") ; 

cBytes = GpiQueryMetaFileLength(hmf); /* gets length of metafile */ 

/* Allocate the buffer for the metafile data. */ 

DosAllocMem((VOID *)pbBuffer, (ULONG)cBytes, 

PAG_COMMIT | PAG_READ | PAG_WRITE) ; 

GpiQueryMetaFileBits( 

hmf, /* handle of metafile */ 

off, /* offset of next byte to retrieve */ 

cBytes, /* length of data */ 

pbBuffer); /* buffer to receive metafile data */ 
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GpiQueryMetaFileLength - 
Query Metafile Length 


#define INCL_GPIMETAFILES /* Or use INCL_GPI or INCL_PM */ 


LONG GpiQueryMetaFileLength (HMF hmf) 


This function returns the total length of a memory metafile, in bytes. 

Parameters 

hmf (HMF) - input 

Memory-metafile handle. 


Returns 

Total length of the metafile: 

>0 Total length of the metafile 

GPI_ALTERROR Error. 

Possible returns from WinGetLastError 

PMERR_INV_HMF An invalid metafile handle was specified. 

PMERR_TOO_MANY_METAFILES_IN_USE The maximum number of metafiles allowed for a given 

process was exceeded. 

Remarks 

This function is normally used before GpiQueryMetaFileBits. 

Example Code 

This example uses GpiQueryMetaFileLength to query the byte length of a memory metafile. 

Idefine INCL_GPIMETAFILES /* Meta File functions */ 

linclude <os2.h> 

HMF hmf; /* memory -metafile handle */ 

LONG 1 Length; /* length of metafile */ 

1 Length = GpiQueryMetaFileLength(hmf) ; 


Chapter 5. Graphics Functions 5-323 






GpiQueryMix 
Query Mix 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


LONG GpiQueryMix (HPS bps) 


This function returns the current value of the (character) foreground color-mixing mode, as set by the 
GpiSetMix function. 

Parameters 

bps (HPS) - input 

Presentation-space handle. 


Returns 

Mix mode: 

FM_DEFAULT Default 
>0 Mix mode 

FM_ERROR Error. 

Possible returns from WinGetLastError 

PMERR_INV_HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_IN_RETAIN_MODE An attempt was made to issue a function (for example, 

query) that is invalid when the actual drawing mode is not 

draw or draw-and-retaln. 

PMERR_INV_DC_TYPE An invalid type parameter was specified with 

DevOpenDC, or a function was issued that is invalid for a 
OD_METAFILE_NOQUERY device context. 

Remarks 

This function is invalid when the drawing mode (see GpiSetDrawingMode) is set to retain. 

Example Code 

This example uses GpiQueryMix to return the current foreground-mixing mode after setting the draw 
mode to DRAW. 


Idefine INCL_GPIPRIMITIVES /* Primitive functions */ 
Idefine INCL_GPICONTROL /* Control functions */ 
linclude <os2.h> 

HPS hps; /* Presentation-space handle */ 
LONG IMixMode; /* mix mode */ 


if (GpiSetDrawingMode(hps, DM_DRAW) == TRUE) 
IMixMode = GpiQueryMix(hps) ; 
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GpiQueryModelTransformMatrix - 
Query Model Transform Matrix 


#define INCL_GPITRANSFORMS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiQueryModelTransformMatrix (HPS hps, LONG ICount, PMATRIXLF pmatlfArray) 


This function returns the current model transform; see GpiSetModelTransformMatrix. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

ICount (LONG) - input 
Number of elements. 

The number of elements to be returned in pmatlfArray, must be in the range 0 through 9. If 0 is 
specified, no matrix elements are returned. 

pmatlfArray (PMATRIXLF) - output 
Transform matrix. 

A structure in which the elements of the model transform matrix are returned. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 


PMERRINVHPS 

PMERRPSBUSY 

PMERRINVINRETAINMODE 

PMERR_INV_LENGTH_OR_COUNT 

PMERR_INV_DC_TYPE 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An attempt was made to issue a function (for example, 
query) that is invalid when the actual drawing mode is not 

draw or draw-and-retaln. 

An invalid length or count parameter was specified. 

An invalid type parameter was specified with 
DevOpenDC, or a function was issued that is invalid for a 
OD_M ETAFI LE_NOQU E RY device context. 


Remarks 

This function is invalid when the drawing mode (see GpiSetDrawingMode) is set to retain. 
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GpiGuery ModelT ransformMatrix 
Query Model Transform Matrix 


Example Code 

This example uses GpiQueryModelTransformMatrix to query the first element of the current model 
transform after setting the draw mode to DRAW. 


Idefine INCL_GPITRANSFORMS /* Transform functions */ 
Idefine INCL_GPICONTROL /* Control functions */ 
linclude <os2.h> 

BOOL fSuccess; /* success indicator */ 
HPS hps; /* Presentation-space handle */ 
LONG 1 Count; /* number of elements */ 
MATRIXLF pmatlfArray; /* transform matrix */ 


1 Count = 1; /* examine only first element of transform matrix */ 

if (GpiSetDrawingMode(hps, DM_DRAW) == TRUE) 

fSuccess = GpiQueryModelTransformMatrix(hps, ICount, 

&pmatlf Array) ; 
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GpiQueryNearestColor - 
Query Nearest Color 


^define INCL_GPILOGCOLORTABLE /* Or use INCL_GPI or INCL_PM */ 


LONG GpiQueryNearestColor (HPS hps, ULONG ulOptlons, LONG IRgbln) 


This function returns the nearest color available to the color specified on the currently associated 
device. Both colors are specified in RGB terms. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

ulOptlons (ULONG) - input 
Options: 

Reserved, must be zero. 

IRgbln (LONG) - input 
Required color. 


Returns 

Nearest available color to the one specified: 

>0 Nearest available color 

GPI_ALTERROR Error. 

Possible returns from WinGetLastError 

PMERRJNV HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_COLOR_OPTIONS An invalid options parameter was specified with a logical 

color table or color query function. 

PMERR_INV_RGBCOLOR An invalid rgb color parameter was specified with 

GpiQueryNearestColor or GpiQueryColor 

Remarks 

The nearest color returned is one that is available in the physical palette on the device. This might 
not actually be available with the currently loaded logical color table. 

The color returned is a pure color, that is, one that can be used for drawing lines, text, and so on. It 
does not take into account the possibility of dithered colors being used for filled areas. With 
dithering, it is likely that the color used for filling areas is different from that used for lines, and text, 
when the same color index is selected. 

For a monochrome device, if IRgbln is the reset color, then IRgbOut is also the reset color; 
otherwise, it is black if the reset color is white, and the converse. 
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GpiQueryNearestColor - 
Query Nearest Color 

Example Code 

This example uses GpiQueryNearestColor to return the nearest color available to the one specified, 
on the currently associated device. 


Idefine INCL_GPILOGCOLORTABLE /* Color Table functions */ 
linclude <os2.h> 

LONG lRgbOut; /* nearest color */ 
HPS hps; /* Presentation-space handle */ 
ULONG ul Options; /* options */ 
LONG lRgbln; /* color to match */ 


/* reserved; set to 0 */ 
ulOptions = 0L; 

/* color to find index for */ 

lRgbln = (PC_RESERVED*16777216) + (0*65536) + (0*256) + 1; 
lRgbOut = GpiQueryNearestColor(hps, ulOptions, lRgbln); 
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GpiQueryNumberSetlds - 
Query Number Set Identifiers 


#define INCL_GPILCIDS /* Or use INCL_GPI or INCL_PM 7 


LONG GpiQueryNumberSetlds (HPS bps) 


This function returns the number of local identifiers (Icids) currently in use, referring to fonts or bit 
maps. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 


Returns 

Number of Icids: 

>0 Number of Icids in use 

GPI_ALTERROR Error. 

Possible returns from WinGetLastError 

PMERR_INV_HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

Remarks 

LCID_DEFAULT is included if the default font has been changed (see GpiCreateLogFont). 

The information returned by this call can be used to perform a subsequent GpiQuerySetlds request. 

Example Code 

This example uses GpiQueryNumberSetlds to return the number of local identifiers in use (font and 
bit map). 

Idefine INCL_GPILCIDS /* Font functions */ 

linclude <os2.h> 

LONG 1 Count; /* number of lcid's */ 

HPS hps; /* Presentation-space handle */ 

ICount = GpiQueryNumberSetlds (hps) ; 
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GpiQueryPageViewport 
Query Page Viewport 


#define INCL_GPITRANSFORMS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiQueryPageViewport (HPS hps, PRECTL prcIViewport) 


This function returns the page viewport; see GpiSetPageViewport. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

prcIViewport (PRECTL) - output 
Page viewport. 

The size and position of the page viewport in device units. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 

PMERRJNV HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_IN_RETAIN_MODE An attempt was made to issue a function (for example, 

query) that is invalid when the actual drawing mode is not 

draw or draw-and-retain. 

PMERR_INV_DC_TYPE An invalid type parameter was specified with 

DevOpenDC, or a function was issued that is invalid for a 
OD_METAFILE_NOQUERY device context. 


Remarks 

This function must not be issued when there is no device context associated with the presentation 
space. 
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GpiQueryPageViewport - 
Query Page Viewport 


Example Code 

This example uses GpiQueryPageViewport to query the page viewport, after associating a device 
context to the presentation space; if successful, it assigns the x coordinate of the viewport to a 
variable. 


Idefine INCL_GPITRANSFORMS /* Transform functions */ 
# include <os2.h> 

BOOL fSuccess; /* success indicator */ 
HPS hps; /* Presentation-space handle */ 
RECTL prclViewport; /* page. viewport */ 
LONG lLwrLftxCoord; /* lower left x coordinate of field */ 
HDC hdc; /* device context handle */ 


/* associate device context */ 
if (GpiAssociate(hps, hdc) == TRUE) 

{ 

fSuccess = GpiQueryPageViewport(hps, &prcl Viewport); 

/* if successful, assign lower left x coordinate of viewport */ 
if (fSuccess == TRUE) 

lLwrLftxCoord = prclViewport.xLeft; 

} 
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GpiQueryPalette 
Query Palette 


#define INCL_GPILOGCOLORTABLE /* Or use INCL_GPI or INCL_PM */ 


HPAL GpiQueryPalette (HPS hps) 


This function returns the handle of the palette currently selected into a presentation space. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 


Returns 

Palette handle. 

NULLHANDLE Null handle (no palette is selected) 

PAL_ERROR Error occurred 

Otherwise Handle of the palette currently selected into this presentation space. 

Possible returns from WinGetLastError 

PMERR INV HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 


Remarks 

It is possible for a palette to be selected into more than one presentation space at any one time. See 
GpiSelectPalette. 

Example Code 

This example uses GpiQueryPalette to return the handle of the palette currently selected into a 
presentation space and then calls GpiDeletePalette to delete the palette. 


Idefine INCL_GPILOGCOLORTABLE /* Color Table functions */ 
finclude <os2.h> 

HPAL hpal; /* palette handle */ 
HPS hps; /* Presentation-space handle */ 
BOOL f Success; /* success indicator */ 


/* get handle of currently associated palette */ 
hpal = GpiQueryPalette(hps) ; 

/* delete palette */ 
f Success = Gpi Del etePalette( hpal ) ; 
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GpiQueryPalettelnfo - 
Query Palette Info 


#define INCL_GPILOGCOLORTABLE /* Or use INCL_GPI or INCL_PM */ 


LONG GpiQueryPalettelnfo (HPAL hpal, HPS tips, ULONG flOptlons, LONG IStart, 

LONG ICount, PLONG aiArray) 


This function passes back the information for a palette. 


Parameters 

hpal (HPAL) - input 
Palette handle. 

hps (HPS) - input 

Presentation-space handle. 

flOptlons (ULONG) - input 
Specifies options: 

LCOLOPTJNDEX If this is set, the index is to be returned for each RGB value in the aiArray 
parameter. 

Other flags are reserved and must be 0. 

IStart (LONG) - input 

The starting index for which data is to be returned. 

ICount (LONG) - input 
Count of elements. 

Number of elements available in aiArray. 

If 0 is specified, the number of elements required to return the palette information in aiArray is 
returned. 

aiArray (PLONG) - output 

An array in which the palette information is returned. 

If LCOLOPTJNDEX is not specified, this is an array of RGB values (each value is as defined for 
GpiCreatePalette), starting with the specified index, and ending either when there are no further 
entries in the palette, or when aiArray has been exhausted. If the palette is not loaded with a 
contiguous set of indices, QLCTJMOTLOADED is returned as the RGB value for any index values, 
outside the default range, that have not been explicitly loaded. 

If LCOLOPTJNDEX is specified, this is an array of alternating color indices and RGB values, in 

the order index"!, RGB value"!, index2, RGB value2 An even number of elements is always 

returned, if the palette is not loaded with a contiguous set of indices, any index values that are 
not present are skipped. 


Returns 

Number of elements: 

PAL_ERROR Error occurred 

Otherwise The number of elements of palette information passed back in the aiArray 

parameter, unless ICount parameter is 0, in which case this is the total number of 
elements that are needed to hold the palette information. 

Zero is returned if no palette is selected. 

Possible returns from WinGetLastError 

PMERR INV HPS An invalid presentation-space handle was specified. 
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GpiQueryPalettelnfo 
Query Palette Info 


PMERR_PS_BUSY 

PMERRINVHPAL 

PM ERR _INV_COLOR_OPTIONS 

PMERR_INV_COLOR_START_INDEX 

PMERR_INV_LENGTH_OR_COUNT 


An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid color palette handle was specified. 

An invalid options parameter was specified with a logical 
color table or color query function. 

An invalid starting index parameter was specified with a 
logical color table or color query function. 

An invalid length or count parameter was specified. 


PMERR_PALETTE_BUSY 


An attempt has been made to reset the owner of a palette 
when it was busy. 


Remarks 

The information passed back is in the same format as that required to create a palette (see 
GpiCreatePalette). 

If a non-NULL palette handle is passed in the hpal parameter, the information is returned for that 
palette, and the hps parameter is ignored. Otherwise, hps identifies a presentation space for which 
the default colors are returned as a palette. 

Note: In this case the default colors are returned, even if a logical color table is currently loaded 
into the presentation space. 


Example Code 

This example uses GpiQueryPalettelnfo to query the palette information and, if any values are 
returned, assigns the palette's first color value to a variable. 


Idefine INCL_GPILOGCOLORTABLE /* Color Table functions 
linclude <os2.h> 


LONG IRetCount; /* 
HPAL hpal; /* 
ULONG fl Options; /* 
ULONG ul Start; /* 
ULONG ul Count; /* 
ULONG *aul Array; /* 
ULONG ulFirstColor; /* 


/* specify no options */ 
flOptions = 0L; 

/* start at index 0 */ 
ul Start = 0L; 


number of elements 
palette handle 
options 

starting index 
count of elements in array 
palette information array 
first color in palette 


/* tell function to determine element count */ 
ul Count = OL; 


*/ 


*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 


IRetCount = GpiQueryPaletteInfo(hpal , NULLHANDLE, flOptions, 

ul Start, ul Count, 
aul Array) ; 


/* if palette info returned, assign value of first color */ 
ulFirstColor = aul Array [0]; 
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GpiQueryPattern - 
Query Pattern 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM. Also in COMMON section */ 


LONG GpiQueryPattern (HPS hps) 


This function returns the current value of the shading-pattern symbol, as set by the GpiSetPattern 
function. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 


Returns 

Pattern symbol: 

PATSYM_DEFAULT Default 
>0 Pattern symbol 

PATSYM_ERROR Error. 

Possible returns from WinGetLastError 

PMERR_INV_HPS 
PMERRPSBUSY 


PMERR _INV _IN_RET AINMODE 


PMERR_INV_DC_TYPE 


Remarks 

This function is invalid when the drawing 


Example Code 

In this example we query the current value of the shading-pattern symbol, as set by the 
GpiSetPattern call. 

Idefine INCL_GPIPRIMITIVES 
linclude <0S2.H> 

LONG 1 Result; /* pattern symbol if > 0 */ 

HPS hps; /* Presentation space handle. */ 

if (PATSYM_SOLID = GpiQueryPattern(hps)) 

{ 

/* • */ 

/* . */ 

} 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An attempt was made to issue a function (for example, 
query) that is invalid when the actual drawing mode is not 

draw or draw-and-retaln. 

An invalid type parameter was specified with 
DevOpenDC, or a function was issued that is invalid for a 
OD_METAFILE_NOQUERY device context. 


mode (see GpiSetDrawingMode) is set to retain. 
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GpiQueryPatternRefPoint - 
Query Pattern Reference Point 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiQueryPatternRefPoint (HPS bps, PPOINTL pptiRefPoInt) 


This function returns the current pattern reference point, as set by the GpiSetPatternRefPoint 
function. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

pptiRefPoInt (PPOINTL) - output 
Pattern reference point. 

If the pattern reference point is currently set to the default, (0,0) is returned. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 

PMERRINVHPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_IN_RETAIN_MODE An attempt was made to issue a function (for example, 

query) that is invalid when the actual drawing mode is not 

draw or draw-and-retain. 

PMERR_INV_DC_TYPE An invalid type parameter was specified with 

DevOpenDC, or a function was issued that is invalid for a 
OD_METAFILE_NOQUERY device context. 


Remarks 

This function is invalid when the drawing mode (see GpiSetDrawingMode) is set to retain. 


Example Code 

In this example we query the pattern reference point, which is set by the GpiSetPatternRefPoint. 

Idefine INCL_GPIPRIMITIVES 
linclude <0S2.H> 

BOOL fl Result; 

HPS hps; /* Presentation space handle. */ 

POINTL ptlRefPoint; /* pattern reference point */ 

LONG xcoord, ycoord; 

fl Result = GpiQueryPatternRefPoint (hps, 

UptlRefPoint ); 

xcoord = ptlRefPoint. x; ycoord = ptlRefPoint.y; 
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GpiQueryPatternSet - 
Query Pattern Set 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


LONG GpiQueryPatternSet (HPS hps) 


This function returns the current value of the pattern-set identifier, as set by the GpiSetPatternSet 
function. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 


Returns 


Pattern-set local identifier: 

LCID_DEFAULT Default 
>0 Pattern set 

LCID_ERROR Error. 


Possible returns from WinGetLastError 

PMERR_INV_HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR _INV_IN_RETAIN_MODE An attempt was made to issue a function (for example, 

query) that is invalid when the actual drawing mode is not 

draw or draw-and-retaln. 

PMERR_INV_DC_TYPE An invalid type parameter was specified with 

DevOpenDC, or a function was issued that is invalid for a 
OD_METAFILE_NOQUERY device context. 


Remarks 

This function is not valid when the drawing mode (see GpiSetDrawingMode) is set to retain. 

Example Code 

In this example we query the pattern set identifier, which is set by the GpiSetPatternSet. 

Idefine INCL_GPIPRIMITIVES 
linclude <0S2.H> 

LONG lpatternset; 

HPS hps; /* Presentation space handle. */ 

lpatternset = GpiQueryPatternSet(hps) ; 
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GpiQueryPel 
Query Pel 


#define INCL_GPIBITMAPS /* Or use INCL_GPI or INCL_PM */ 


LONG GpiQueryPel (HPS hps, PPOINTL pptlPolnl) 


This function returns the color of a pel at a position specified in world coordinates. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

pptIPoInt (PPOINTL) - input 

Position in world coordinates. 

It is an error if the specified point is outside any of the current clipping objects (that is, clip path, 
viewing limits, clip region, or visible region). 


Returns 

Color index of the pel: 

>0 Color of the pel 

CLR_NOINDEX No valid index (color is not in logical color table) 

GPI_ALTERROR Error. 

Possible returns from WinGetLastError 

PMERRINVHPS 
PMERRPSBUSY 

PMERRINVCOORDINATE 
PMERRPELISCLIPPED 

PMERR_PEL_NOT_ AVAILABLE 

PMERRNOBITMAPSELECTED 
PMERR_INV_DC_TYPE 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid coordinate value was specified. 

An attempt was made to query a pel that had been 
clipped using GpiQueryPel. 

An attempt was made to query a pel that did not exist in 
GpiQueryPel (for example, a memory device context with 
no selected bit map). 

An attempt has been made to operate on a memory 
device context that has no bit map selected. 

An invalid type parameter was specified with 
DevOpenDC, or a function was issued that is invalid for a 
ODMETAFILENOQUERY device context. 


Remarks 

The color returned is a color index or RGB value, according to the logical color table in force (see 
GpiCreateLogColorTable). 
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GpiQueryPel - 
Query Pel 


Example Code 

In this example we query the color of a pel at a position specified in world coordinates. 

Idefine I NCL_GPI BITMAPS 
linclude <0S2.H> 

LONG lcolorindex; /* color index of pel. */ 

HPS hps; /* Presentation space handle. */ 

POINTL ptl Point; /* position in world coordinates. */ 

LONG xcoord, ycoord; 

GpiQueryPel (hps, &ptl Poi nt ) ; 

xcoord = ptlPoint.x; ycoord = ptlPoint.y; 


Chapter 5. Graphics Functions 5-339 



GpiQueryPickAperturePosition 
Query Pick Aperture Position 


#define INCL_GPICORRELATION /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiQueryPickAperturePosition (HPS hps, PPOINTL pptiPoint) 


This function returns the position of the center of the pick aperture. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

pptiPoint (PPOINTL) - output 
Pick-aperture position. 

Position of the center of the pick aperture, in presentation-page coordinates. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRINVHPS 

PMERR_PS_BUSY 

P M E R RJN V_DC_T YPE 


Related Functions 

• GpiQueryPickAperturePosition 

• GpiSetPickAperturePosition 

• GpiQueryPickApertureSize 

Example Code 

In this example we query the position of the center of the pick aperture. 

Idefine INCL_GPICORELATION 
linclude <0S2.H> 

BOOL fl Result; 

HPS hps; /* Presentation space handle. */ 

POINTL ptl Ref Point; /* Pick-aperture position. */ 

LONG xcoord, ycoord; 

flResult = GpiPickAperturePosition(hps, &ptl Ref Poi nt) ; 
xcoord = ptlRefPoint.x; ycoord = ptlRefPoint.y; 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid type parameter was specified with 
DevOpenDC, or a function was issued that is invalid for a 
OD_METAFILE_NOQUERY device context. 
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GpiQueryPickApertureSize - 
Query Pick Aperture Size 


#define INCL_GPICORRELATION /* Or use INCL_GPI or INCL_PM 7 


BOOL GpiQueryPickApertureSize (HPS hps, PSIZEL psiziSize) 


This function returns the value of the pick-aperture size, as set by the GpiSetPickApertureSize 
function. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

psiziSize (PSIZEL) - output 
Pick-aperture size. 

Size of the pick aperture, in presentation-page coordinates. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRINVHPS 
PMERRPSBUSY 

PMERR_INV_DC_TYPE 


Example Code 

In this example we query the pick-aperture size, as set by the GpiSetPickApertureSize call. 

Idefine INCL_GPICORRELATION 
linclude <0S2.H> 

BOOL fl Result; 

HPS hps; /* Presentation space handle. */ 

SIZEL sizel; /* Pick-aperture position. */ 

LONG xcoord, ycoord; 

flResult = GpiQueryPickApertureSize(hps, &sizel); 
xcoord = sizel. cx; ycoord = sizel. cy; 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid type parameter was specified with 
DevOpenDC, or a function was issued that is invalid for a 
OD_METAFILE_NOQUERY device context. 
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GpiQueryPS - 
Query Presentation Space 


#define INCL_GPICONTROL /* Or use INCL_GPI or INCL_PM 7 


LONG GpiQueryPS (HPS hps, PSIZEL psIziSize) 


This function returns page parameters for the presentation space. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

psizISize (PSIZEL) - output 
Presentation-page size. 


Returns 

Presentation-space options. 

For details, see the GpiCreatePS function. 

The individual fields of the presentation-space options can be extracted by ANDing the returned 
value with the appropriate constant. 

The PS_ASSOCIATE field of flOptions (see GpiCreatePS) should not be used on this function. 
The value of this field is not necessarily the same value that is specified when the presentation 
space is created. 

PS_UNITS Presentation-space size units 

PS_FORMAT Presentation-space coordinate format 

PS_TYPE Presentation-space type 

PS_MODE Presentation-space mode. 


Possible returns from WinGetLastError 

PMERR_INV_HPS 
PMERR PS BUSY 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 


Example Code 

In this example we query the presentation space that corresponds to handle hps. 

Idefine INCL_GPICONTROL 
linclude <0S2.H> 

HPS hps; 

SIZEL size! ; 

GpiQueryPS (hps, &si zel ) ; 
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GpiQueryRealColors - 
Query Real Colors 


#define INCL_GPILOGCOLORTABLE /* Or use INCL_GPI or INCL_PM */ 


LONG GpiQueryRealColors (HPS hps, ULONG ulOptlons, LONG IStart, LONG ICount, 

PLONG alColors) 


This function returns the RGB values of the distinct colors available on the currently associated 
device. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

ulOptlons (ULONG) - input 
Options: 

LCOLOPTJNDEX 


Other 

IStart (LONG) - input 

Ordinal number of the first color required. 

To start the sequence, this parameter is set to 0. 

Note: This parameter is not the color index, and the order in which the colors are returned is 
not defined. 

ICount (LONG) - input 

Maximum number of elements. 

Number of elements available in alColors. 

alColors (PLONG) - output 

Array in which the information is returned. 

Contents depend on the setting of the LCOLOPTJNDEX flag: 

0 An array of color values (each value is as defined for GpiCreateLogColorTable). 

1 An array of alternating color indexes and values, in the order indexl, valuel, index2, value2,... 
indexn, valuen. An even number of elements is always returned in this case. 


If this is specified, the index is to be returned for each RGB value. 

If this flag is set when RGB mode is in force (LCOLF RGB is set on 
GpiCreateLogColorTable), the RGB value is returned as the index. 

Any color not available with the current logical color table is given a special 
index value of CLR_NOINDEX. 

If it is not specified (flag is not set) index values are not returned. 

Other bits are reserved, and must be 0. 


Returns 

Number of elements returned: 

>0 Number of elements returned 

GPI_ALTERROR Error. 

Possible returns from WinGetLastError 

PMERR INV HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 


Chapter 5. Graphics Functions 5-343 





GpiQueryRealColors 
Query Real Colors 


PMERR_INV_LENGTH_OR_COUNT An invalid length or count parameter was specified. 


PMERR_INV_COLOR_OPTIONS An invalid options parameter was specified with a logical 

color table or color query function. 

PMERR_INV_COLOR_START_INDEX An invalid starting index parameter was specified with a 

logical color table or color query function. 


Remarks 

Subject to space in the alColors parameter, all colors that are physically available on the device are 
returned. 

Use of the palette manager by other applications can effect the the physical colors available on the 
device. The available colors can change as a result of palette management, when this occurs a 
WMREALIZEP ALETTE message is sent to all applications. 

Example Code 

In this example we obtain the RGB values of the distinct colors available on the currently associated 
device. 


Idefine INCL_GPILOGCOLORTABLE 
linclude <0S2.H> 

LONG 1 Result; /* number of elements returned */ 

HPS bps; /* Presentation space handle. */ 

ULONG fl Options; /* options */ 

LONG 1 Start; /* ordinal number of first color */ 

LONG 1 Count; /* maximum number of elements */ 

LONG alColors [5]; /* array containing return information */ 

flOptions = LCOLOPTINDEX; /* return index for each RGB value. */ 
1 Start = 0L; /* start sequence at 0. */ 

1 Count = 5L; /* maximum of 5 elements. */ 

1 Result = GpiQueryRealColors(hps, 

flOptions, 

1 Start, 

1 Count, 
alColors) ; 
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GpiQueryRegionBox - 
Query Region Box 


#define INCL_GPIREGIONS /* Or use INCL_GPI or INCL_PM */ 


LONG GpiQueryRegionBox (HPS hps, HRGN hrgn, PRECTL prciBound) 


This function returns the dimensions of the smallest rectangle able to bound the region. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

The region must be owned by the device identified by the currently associated device context. 

hrgn (HRGN) - input 
Region handle. 

prciBound (PRECTL) - output 
Bounding rectangle. 


Returns 

Complexity of region and error indicators: 
RGN_NULL Null region 

RGN_RECT Rectangular region 

RGN_COMPLEX Complex region 
RGN ERROR Error. 


Possible returns from WinGetLastError 


PMERR_INV_HPS 

PMERRPSBUSY 

PMERRINVHRGN 

PMERRREGIONISCLIPREGION 

PMERRHRGNBUSY 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid region handle was specified. 

An attempt was made to perform a region operation on a 
region that is selected as a clip region. 

An internal region busy error was detected. The region 
was locked by one thread during an attempt to access it 
from another thread. 


Remarks 

If the region is null, the rectangle returned has the left boundary equal to the right, and the top 
boundary equal to the bottom. 

It is invalid if the specified region is currently selected as the clip region (by GpiSetClipReglon). 
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GpiQueryRegionBox - 
Query Region Box 

Example Code 

In this example we determine the dimensions of the smallest rectangle able to bound the region. 

Idefine INCL_GPIPREGIONS 
linclude <0S2.H> 

LONG 1 Result; /* number of elements returned */ 

HPS hps; /* Presentation space handle. */ 

HRGN hrgn; /* region handle */ 

RECTL rcl Bound; /* bounding rectangle */ 

IResult = GpiQueryRegionBox(hps, 

(VOID *)hrgn, 

(PRECTL)&rcl Bound); 
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GpiQueryRegionRects - 
Query Region Rectangles 


#define INCL_GPIREGIONS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiQueryRegionRects (HPS hps, HRGN hrgn, PRECTL prcIBound, 

PRGNRECT prgnrcControl, PRECTL arcIRects) 


This function returns the rectangles that, when ORed together, define the specified region. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

The region must be owned by the device identified by the currently associated device context. 

hrgn (HRGN) - input 
Region handle. 

prcIBound (PRECTL) - input 
Bounding rectangle. 

NULL Return all the rectangles in the region. 

Other Return only rectangles that intersect with the bounding rectangle. Each rectangle 
returned is the intersection of the bounding rectangle with a rectangle in the region. 

prgnrcControl (PRGNRECT) - input/output 
Processing-control structure. 

arcIRects (PRECTL) - output 

Array of rectangle structures, in which the rectangles are returned. 

The maximum number of rectangles that can be returned is specified by the crc parameter of the 
RGNRECT structure identified by the prgnrcControl parameter. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 


PMERRINVHPS 

PMERRPSBUSY 

PMERRINVHRGN 

PMERRJNVREGIONCONTROL 

PMERRJNVCOORDINATE 

PMERRJNVRECT 

PMERRREGIONISCLIPREGION 

PMERR_HRGN BUSY 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid region handle was specified. 

An invalid control parameter was specified with 
GpiQueryRegionRects. 

An invalid coordinate value was specified. 

An invalid rectangle parameter was specified. 

An attempt was made to perform a region operation on a 
region that is selected as a clip region. 

An internal region busy error was detected. The region 
was locked by one thread during an attempt to access it 
from another thread. 
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GpiQueryRegionRects - 
Query Region Rectangles 


Remarks 

Points on the right-hand and top boundaries are not included in the region. Points on the left-hand 
and bottom boundaries, that are not also on the right-hand or top boundaries (that is, the top-left and 
bottom-right corner points), are included. 

It is invalid if the specified region is currently selected as the clip region (by GpiSetClipRegion). 

Example Code 

In this example we determine the rectangles that can be OR'ed together to determine the specified 
region. 


Idefine INCL_GPIREGIONS 
linclude <0S2.H> 
Idefine maxrects 12 


BOOL fl Result; /* success indicator. */ 

HPS hps; /* presentation space handle. */ 

HRGN hrgn; /* region handle. */ 

RECTL rcl Bound; /* bounding rectangle */ 

RGNRECT rgnrcControl ; /* processing control */ 

RECTL arcl Rect [maxrects] ; /* array of rectangle structures 

/* in which the rectangles are */ 
/* returned. */ 


rgnrcControl .i restart = 1; /* start numbering rectangles */ 

/* from 1. */ 

rgnrcControl .crc = maxrects; /* maximum number of rectangles */ 

/* that can be returned. */ 

rgnrcControl .usDi recti on = RECTDIR_LFRT_TOPBOT; 

/* order rectangles left-to-right */ 
/* and top-to-bottom. */ 

flResult = GpiQueryRegionRects(hps, 

hrgn, 

&rcl Bound, /* output */ 
&rgnrcControl , 

/* prgnrcControl .crcReturned is the number */ 

/* of rectangles returned. */ 

&arcl Rect [0] ) ; 
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GpiQueryRGBColor - 
Query RGB Color 


#define INCL_GPILOGCOLORTABLE /* Or use INCL_GPI or INCL_PM */ 


LONG GpiQueryRGBColor (HPS hps, ULONG flOptlons, LONG IColorlndex) 


This function returns the actual RGB color that results from a particular index on the 
currently-associated device. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

flOptlons (ULONG) - input 
Options: 

LCOLOPT_REALIZED 

If this is specified, the information is required for when the logical color table is realized. 

If it is not specified (flag is not set) the information is required for when the logical color table 
(if any) is not realized. 

Other bits are reserved, and must be 0. 

IColorlndex (LONG) - input 
Color index. 

This can be any normally valid color index value (see GpiSetColor) except CLR_DEFAULT. 


Returns 

RGB color providing closest match to the specified color index: 
>0 RGB color providing closest match 

GPI_ALTERROR Error. 


Possible returns from WinGetLastError 

PMERRJNVHPS 

PMERRPSBUSY 

PMERR_INV_COLOR_OPTIONS 

PMERRJNVCOLORJNDEX 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid options parameter was specified with a logical 
color table or color query function. 

An invalid color index parameter was specified with 
GpiQueryRGBColor. 


Remarks 

If an RGB logical color table has been loaded, this function returns the nearest RGB color. This 
function is then equivalent to GpiQueryNearestColor. 
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GpiQueryRGBColor 
Query RGB Color 


Example Code 

This example uses the GpiQueryRGBColor call to determine if the color white is available. 

#define INCL_GPILOGCOLORTABLE 
linclude <0S2.H> 

LONG 1 Result; /* closest match to the specified index */ 

HPS hps; /* Presentation space handle. */ 

ULONG fl Opt ions; /* options */ 

LONG IColorIndex; /* color index */ 

1 Col orlndex = CLR_WHITE; 
fl Options = LCOLOPT_REALIZED; 

/* information is required for when the */ 

/* logical color table is realized. */ 

IResult = GpiQueryRGBColor(hps, 

fl Options, 

IColorIndex ); 
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GpiQuerySegmentAttrs - 
Query Segment Attributes 


#define INCL_GPISEGMENTS /* Or use INCL_GPI or INCL_PM */ 


LONG GpiQuerySegmentAttrs (HPS hps, LONG ISegid, LONG lAttrlbute) 


This function returns the current value of the specified attribute as set by the GpiSetSegmentAttrs 
function. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

ISegid (LONG) - input 

Segment identifier; must be greater than 0. 

The name of the segment for which attribute information is to be returned. 

lAttrlbute (LONG) - input 
Attribute to be queried. 

For details of the following attributes, seethe GpiSetlnitialSegmentAttrs function. 


Identifies the attribute of the segment to be returned by this function: 


ATTR_DETECTABLE 

ATTRVISIBLE 

ATTRCHAINED 

ATTR_DYNAMIC 

ATTRFASTCHAIN 

ATTR_PROP_DETECT ABLE 

ATTR_PROP_VISIBLE 


Detectability 

Visibility 

Chained 

Dynamic 

Fast chaining 

Propagate detectability 

Propagate visibility. 


Returns 

Current attribute value: 
ATTR_ON On/yes 

ATTR_OFF Off/no 

ATTR_ERROR Error. 


Possible returns from WinGetLastError 


PMERR_INV_HPS 

PMERR_PS_BUSY 

PMERRINVSEGNAME 
P M E R R_IN V_SEG_ ATTR 


PMERRSEGNOTFOUND 
P ME R R_IN V_M ICROPS_FUNCTION 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid segment identifier was specified. 

An invalid attribute parameter was specified with 
GpiSetSegmentAttrs, GpiQuerySegmentAttrs, 
GpiSetlnitialSegmentAttrs, or 
GpiQuerylnitialSegmentAttrs. 

The specified segment identifier did not exist 

An attempt was made to issue a function that is invalid in 
a micro presentation space. 
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GpiQuerySegmentAttrs - 
Query Segment Attributes 


Remarks 

The segment can be any retained segment, including the currently open one if this is retained. 

Example Code 

This function is used to query the current value of the specified attribute. 

Idefine INCL_GPISEGMENTS 
linclude <0S2.H> 


LONG lSegid; /* Segment identifier must */ 

LONG lvalue; /* be greater than 0. */ 

LONG lattribute; /* attribute to be queried */ 

HPS hps; /* Presentation-space */ 

/* handle. */ 


lattribute = ATTR_V I S I B LE ; 

lvalue = GpiQuerySegmentAttrs (hps, 

lSegid, 
lattribute) ; 


5-352 PM Programming Reference 



GpiQuerySegmentNames - 
Query Segment Names 


#define INCL_GPISEGMENTS /* Or use INCL_GPI or INCL_PM */ 


LONG GpiQuerySegmentNames (HPS hps, LONG IFIrstSegld, LONG ILastSegld, LONG IMax, 

PLONG alSeglds) 


This function returns the identifiers of all segments that exist with identifiers in a specified range. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

IFIrstSegld (LONG) - input 

First segment in the range (must be greater than 0). 

ILastSegld (LONG) - input 

Last segment in the range (must be greater than 0). 

IMax (LONG) - input 
Maximum number. 

This is the maximum number of segment identifiers to be returned in alSegids. 

alSeglds (PLONG) - output 

Array in which the required identifiers are returned. 


Returns 

Number of identifiers returned: 

>0 Number of identifiers returned 

GPI_ALTERROR Error. 

Possible returns from WinGetLastError 

PMERRINVHPS 
PMERRPSBUSY 

PMERRINVSEGNAME 
PMERR_INV_LENGTH_OR_COUNT 
PMERRJNVMICROPSFUNCTION 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid segment identifier was specified. 

An invalid length or count parameter was specified. 

An attempt was made to issue a function that is invalid in 
a micro presentation space. 


Remarks 

Nonretained segment identifiers are not returned. If IFirstSegid is the same as, or greater than 
ILastSegid, the search terminates after querying only the segment with IFirstSegid. 
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GpiQuerySegmentNames 
Query Segment Names 


Example Code 

This function returns the identifiers of all segments that exist within a specified range. 

Idefine INCL_GPISEGMENTS 
linclude <0S2.H> 

Idefine Maxsegs 5 


LONG IRetCount; 

HPS hps; /* Presentation-space */ 

/* handle. */ 


LONG 1 FirstSegid; /* 
/* 
/* 

LONG lLastSegid; /* 
/* 
/* 


First segment in the */ 
range (must be greater */ 
than 0) . */ 

Last segment in the */ 
range (must be greater */ 
than 0) . */ 


LONG IMax; /* This is the maximum */ 

/* number of segment */ 

/* identifiers to be returned */ 

/* in alSegids. */ 

LONG al Segids [Maxsegs] ; /* Array in which the */ 

/* required identifiers are */ 
/* returned. */ 

1 FirstSegid = 1; 
lLastSegid = Maxsegs; 

IMax = Maxsegs; 


IRetCount = GpiQuerySegmentNames (hps, 

1 FirstSegid, 
1 LastSegid, 
IMax, 

alSegids) ; 
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GpiQuerySegmentPriority - 
Query Segment Priority 


#define INCL_GPISEGMENTS /* Or use INCL_GPI or INCL_PM */ 


LONG GpiQuerySegmentPriority (HPS hps, LONG IRefSegld, LONG lOrder) 


This function returns the identifier of the named segment that is chained immediately before or after 
a specified reference segment. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

IRefSegld (LONG) - input 

Reference-segment identifier. 

lOrder(LONG) - input 

Segment higher or lower. 

Shows whether a segment identifier of a higher or lower priority than identified in the IRefSegid 
parameter is to be returned. Possible values are: 

LOWER_PRI Return the next segment with a lower priority than IRefSegid. If IRefSegid = 0, 
query the identifier of the segment with the lowest priority. 

HIGHER_PRI Return the next segment with a higher priority than IRefSegid. If IRefSegid = 0, 
query the identifier of the segment with the highest priority. 

Returns 

Segment identifier. 

The identifier of the segment that is immediately before or after that specified in the IRefSegid 
parameter: 

>0 Segment identifier. 

0 The segment specified in the IRefSegid parameter is either the lowest-priority 

segment (when lOrder = LOWER_PRI) or the highest-priority segment (when 
lOrder = HIGHER_PRI). 

GPIALTERROR Error. 

Possible returns from WinGetLastError 

PMERR_INV_HPS 
PMERRPSBUSY 

PMERRJNVSEGNAME 
PMERRJNVORDERINGPARM 

PMERRSEGNOTCHAINED 

PMERRSEGNOTFOUND 
PMERRINVMICROPSFUNCTION 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid segment identifier was specified. 

An invalid order parameter was specified with 
GpiSetSegmentPriority. 

An attempt was made to issue GpiDrawFrom, 
GpiCorrelateFrom or GpiQuerySegmentPriority for a 
segment that was not chained. 

The specified segment identifier did not exist 

An attempt was made to issue a function that is invalid in 
a micro presentation space. 
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Query Segment Priority 


Remarks 

The segment that is chained before the specified segment, is considered to have a lower priority 
than the specified segment; similarly, the segment that is chained after the specified segment, is 
considered to have a higher priority than the specified segment. 

Unnamed segments (with an identifier of zero) are ignored. 

Example Code 

This function returns the identifier of the named segment that is chained immediately before or after 
a specified reference segment. 

Idefine INCL_GPISEGMENTS 
linclude <0S2.H> 


HPS hps; /* Presentation-space */ 

/* handle. */ 

LONG lSegid; /* Segment identifier */ 

LONG IRefSegid; /* Reference-segment */ 

/* identifier. */ 

LONG 1 Order; /* Shows whether a */ 

/* segment identifier of a */ 

/* higher or lower priority */ 

/* than identified in the */ 

/* IRefSegid parameter is */ 

/* to be returned. */ 

1 Order = HIGHER_PRI; /* Return the next */ 

/* segment with a higher */ 

/* priority than */ 

/* IRefSegid. If */ 

/* lRefSegid=0, query */ 

/* the identifier of the */ 

/* segment with the */ 

/* highest priority. */ 
IRefSegid = 0; /* find the segment with the highest */ 
/* priority. */ 


lSegid = GpiQuerySegmentPriority (hps, 

IRefSegid, 
1 Order) ; 


5-356 PM Programming Reference 



GpiQuerySegmentTransformMatrix - 
Query Segment Transform Matrix 


#define INCL_GPITRANSFORMS /* Or use INCL_GPI or INCL_PM */ 

BOOL GpiQuerySegmentTransformMatrix (HPS hps, LONG ISegld, LONG ICount, 

PMATRIXLF pmatlf Array) 


This function returns the elements of the transform of the identified segment (see 
GpiSetSegmentTransformMatrix). 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

ISegld (LONG) - input 
Segment identifier. 

ICount (LONG) - input 
Number of elements. 

The number of elements that are to be set in the pmatlf Array parameter. ICount must be in the 
range 0 through 9. 

pmatlfArray (PMATRIXLF) - output 
Transform matrix. 



Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 

PMERRINVHPS 

PMERR_PS_BUSY 

PMERRINVSEGNAME 

PMERR_INV_MICROPS_FUNCTION 

PMERR_INV_LENGTH_OR_COUNT 

PMERR_SEG_NOT_FOUND 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid segment identifier was specified. 

An attempt was made to issue a function that is invalid in 
a micro presentation space. 

An invalid length or count parameter was specified. 

The specified segment identifier did not exist 
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GpiQuerySegmentT ransformMatrix 
Query Segment Transform Matrix 


Example Code 

This function returns the elements of the transform of the identified segment (see 
GpiSetSegmentTransformMatrix). 

Idefine INCL_GPITRANSFORMS /* Or use INCL_GPI or INCL_PM */ 
#include<0S2.H> 

Idefine COUNT 9 

HPS hps; /* Presentation-space */ 

/* handle. */ 

LONG lSegid; /* Segment identifier. */ 

LONG 1 Count; /* The number of elements */ 

/* that are to be set in the */ 

/* pmatlf Array parameter. */ 

/* 1 Count must be in the */ 

/* range 0 through 9. */ 

MATRIXLF pmat If Array [COUNT] ; /* array of Transform matrix */ 

/* structures.. This is an */ 

/* output parameter. */ 

BOOL fSuccess; /* returns true if successful. */ 


fSuccess = GpiQuerySegmentTransformMatrix(hps, 

lSegid, 

1 Count, 
pmat If Array) ; 
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GpiQuerySetlds - 
Query Set Identifiers 


#define INCL_GPILCIDS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiQuerySetlds (HPS hps, LONG ICount, PLONG aiTypes, PSTR8 aNames, 
PLONG allcids) 


This function returns information about all the fonts that have been created by GpiCreateLogFont, 
and tagged bit maps (see GpiSetBitmapid). 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

ICount (LONG) - input 

The number of objects to be queried. 

The number of local identifiers (Icids) currently in use, and therefore the maximum number of 
objects for which information can be returned, can be found with GpiQueryNumberSetlds. 

aiTypes (PLONG) - output 
Object types. 

Elements indicate whether the corresponding allcids element refers to a logical font or a tagged 
bit map. 

LCIDT FONT Font object 

LCIDT_BITMAP Bit map. 

aNames (PSTR8) - output 
Font names. 

An array of ICount consecutive 8-byte fields, in which the 8-character names associated with the 
logical fonts are returned. For bit maps, the whole field is set to zeros. 

allcids (PLONG) - output 
Local identifiers. 

An array in which the local identifier (Icid) values are returned. 

LCID DEFAULT is included if the default font has been changed (see GpiCreateLogFont). 

Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRJNVHPS 
PMERRPSBUSY 

PMERR_INV_LENGTH_OR_COUNT 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid length or count parameter was specified. 
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GpiQuerySetlds - 
Query Set Identifiers 


Remarks 

Each of the output parameters is an array with ICount elements. Information about the first ICount 
objects is returned; if there are fewer than ICount, the alTypes and allcids elements for the 
remainder are cleared to 0. 


Example Code 

This example uses the GpiQuerySetlds function to retrieve the local identifier for all logical fonts. It 
then uses the identifiers to delete the logical fonts. 


Idefine INCL_DOSMEMMGR 
Idefine INCL_GPILCIDS 
linclude <0S2.H> 
Idefine TOTALMEM 200 


HPS hps; /* Presentation-space */ 

/* handle. */ 

LONG ICount; /* The number of objects to */ 


/* be queried. */ 

PLONG alTypes; /* Object types. */ 

ULONG rc; /* Return code. */ 

PSTR8 aNames; /* font names. */ 

PLONG allcids; /* local identifiers. */ 

PLONG pBase; 

USHORT i; 

rc = DosAllocMem((PPVOID)pBase, 


(ULONG) T0TALMEM*s i zeof ( LONG) , 

/* space is needed for an array of */ 
/* ICount longs. */ 

PAG_READ | 

PAG_WRITE | 

PAG_C0MMIT) ; 


ICount = GpiQueryNumberSetlds(hps) ; 

/* The number of local */ 

/* identifiers (lcids) */ 

/* currently in use, and */ 

/* therefore the maximum */ 

/* number of objects for */ 

/* which information can be */ 

/* returned. */ 

rc = DosSubAllocMem((PVOID)pBase, 

(PPVOID)aNames, 

(ULONG) ( 1 Count* (ULONG) s i zeof ( STR8) ) ) ; 

/* space is needed for an array of */ 

/* ICount longs. */ 

rc = DosSubAllocMem((PVOID)pBase, 

(PPVOID) al lcids, 

(UL0NG)lCount*sizeof(L0NG)) ; 

/* space i s needed for an array of */ 

/* ICount longs. */ 

rc = DosSubAllocMem((PVOID)pBase, 

(PPVOID)alTypes, 

(ULONG) 1 Count*si zeof (LONG) ) ; 

/* space is needed for an array of */ 

/* ICount longs. */ 

GpiQuerySetIds(hps, 

ICount, 

alTypes, 

aNames, /* An array of ICount */ 

/* consecutive 8-byte fields, */ 
/* in which the 8-character */ 
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GpiQuerySetlds - 
Query Set Identifiers 


/* names associated with */ 

/* the logical fonts are */ 

/* returned. For bit maps, */ 

/* the whole field is set to */ 

/* zeros. */ 

allcids);/* An array in which the */ 

/* local identifier (lcid) */ 

/* values are returned. */ 

/* LCID DEFAULT is */ 


/* included if the default */ 
/* font has been changed */ 
/* (see GpiCreateLogFont) . */ 

for (i = 1; i < 1 Count; i++) 

{ 

if (al 1 ci ds [i ] == LCIDT_FONT) 

GpiDeleteSetId(hps,allcids[i] ) ; 

} 
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GpiQueryStopDraw 
Query Stop Draw 


#define INCLJ3PICONTROL /* Or use INCL_GPI or INCL_PM */ 


LONG GpiQueryStopDraw (HPS hps) 


This function indicates whether the “stop draw” condition currently exists. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 


Returns 

Stop draw condition indicator: 

SDW_OFF No “stop draw” condition currently exists 
SDW_ON The “stop draw" condition currently exists 
SDW_ERROR Error. 

Possible returns from WinGetLastError 

PMERR_INV_HPS 
PMERR_INV_MICROPS_FUNCTION 


Remarks 

See GpiSetStOpDraw for details. 


Example Code 

This function indicates whether the "stop draw" condition currently exists. 

Idefine INCL_GPICONTROL 
#i nclude <0S2.H> 

HPS hps; /* Presentation-space */ 

/* handle. */ 

LONG lvalue; 

if(GpiQueryStopDraw(hps) = SDW_0FF) 

{ 

/* drawing may proceed; no stop draw */ 

/* condition exists. */ 

} 


An invalid presentation-space handle was specified. 

An attempt was made to issue a function that is invalid in 
a micro presentation space. 
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GpiQueryTag - 
Query Tag 


^define INCL_GPICORRELATION /* Or use INCL_GPI or INCL_PM */ 

BOOL GpiQueryTag (HPS hps, PLONG piTag) 

This function returns the current value of the tag identifier, as set by the GpiSetTag function. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

piTag (PLONG) - output 
Tag identifier. 

Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRINVHPS 
PMERRPSBUSY 

PMERRINVMICROPSFUNCTION 

Remarks 

This function is invalid when the drawing mode (see GpiSetDrawingMode) is set to retain. 

Example Code 

This function returns the current value of the tag identifier, as set by the GpiSetTag call. 

Idefine INCL_GPICORRELATION 
linclude <0S2.H> 

HPS hps; /* Presentation-space */ 

/* handle. */ 

LONG ITag; /* Tag identifier. */ 

GpiQueryTag(hps, 

&1 Tag) ; 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An attempt was made to issue a function that is invalid in 
a micro presentation space. 
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GpiQueryT extAlignment 
Query Text Alignment 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM 7 


BOOL GpiQueryTextAiignment (HPS hps, PLONG piHorlzontal, PLONG pIVerticai) 


This function returns the current value of the text alignment attribute, as set by the 
GpiSetTextAlignment function. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

piHorizontal (PLONG) - output 

Horizontal alignment: The horizontal alignment determines character positioning in a text string. 
The value returned will be one of those described under the GpiSetTextAlignment function. 

pIVerticai (PLONG) - output 

Vertical alignment: The vertical alignment determines character positioning in a text string. The 
value returned will be one of those described under the GpiSetTextAlignment function. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 

PMERRJNV HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_IN_RETAIN_MODE An attempt was made to issue a function (for example, 

query) that is invalid when the actual drawing mode is not 

draw or draw-and-retain. 

PMERR_INV_DC_TYPE An invalid type parameter was specified with 

DevOpenDC, or a function was issued that is invalid for a 
OD_METAFILE_NOQUERY device context. 

Remarks 

This function is invalid when the drawing mode (see GpiSetDrawingMode) is set to retain. 

Support for this function is device dependent. 


Related Functions 

• GpiQueryAttrs 

• GpiSetTextAlignment 
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GpiQueryTextBox - 
Query Text Box 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM 7 


BOOL GpiQueryTextBox (HPS hps, LONG ICountl, PCH pchStrlng, LONG ICount2, 
PPOINTL aptiPoints) 


This function returns the relative coordinates of the four corners of a text box. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

ICountl (LONG) - input 
Number of characters. 

pchStrlng (PCH) - input 
The character string. 

ICount2 (LONG) - input 
Number of points. 

Contains the number of points to be returned in the aptiPoints array. Specify TXTBOXCOUNT to 
get the maximum information. 

aptiPoints (PPOINTL) - output 
List of points. 

The list of points contains the relative coordinates of the text box in world coordinates. The 
array elements are numbered consecutively, starting with TXTBOX_TOPLEFT. The element 
number constants start with 0. Refer to the appropriate bindings reference. A ICountZ value of 
TXTBOX COUNT will cause all of the defined array elements to be returned. 

The terms ‘top-left’, ‘bottom-right’, and so on, are well defined when the character angle is such 
that the baseline is parallel to the x axis and running left to right, and there is no character 
shear. If the character string is rotated or sheared, the term top-left applies to the corner of the 
box that appears in the top-left position when no rotation or shear is applied. 

This is an example: 

Set character angle = -1,1 
String = ABCDE 

Coordinates returned are as shown: 



bottom left 


Figure 5-4. Box Enclosing Characters 
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GpiQueryT extBox 
Query Text Box 


TXTBOX_TOPLEFT 
TXTBOX_BOTTOM LEFT 
TXTBOX_TOP RIGHT 
TXTBOXBOTTOM RIGHT 
TXTBOX_CONCAT 


Top-left corner 
Bottom-left corner 
Top-right corner 
Bottom-right corner 
Concatenation point. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 


PMERRINVHPS 

PMERR_PS_BUSY 

PMERRJNV _IN_RET AINMODE 

P ME R R _INV_LENGTH_OR_C OU NT 
PMERRCOORDINATEOVERFLOW 

PMERR_INV_DC_TYPE 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An attempt was made to issue a function (for example, 
query) that Is invalid when the actual drawing mode is not 

draw or draw-and-retain. 

An invalid length or count parameter was specified. 

An internal coordinate overflow error occurred. This can 
occur if coordinates or matrix transformation elements (or 
both) are invalid or too large. 

An invalid type parameter was specified with 
DevOpenDC, or a function was issued that is invalid for a 
OD_METAFILE_NOQUERY device context. 


Remarks 

The text box is defined as the parallelogram that encloses the specified character string when 
displayed on the device. Also returned are the relative coordinates of the concatenation point; that 
is, the value of current position after an equivalent GpiCharStringAt function. All coordinates are 
relative to the start point. (See GpiSetCharDirection function.) These coordinates can be used to box 
or underline the string, or to change the attributes in the middle of a longer string. 

Note: The height of the string is based on the maximum height of the font (including space for 
descenders, accents, and so on), not the maximum height of the actual characters 'm the 
string. The dimensions of the box do not correspond directly to those of the character box 
(see GpiSetCharBox). 

Character attributes are taken into account as if the string is to be drawn, but no output actually 
occurs. However, if the character mode (see GpiSetCharMode) is CM MODE2 this function should 
only be used if the character angle (see GpiSetCharAngle), character direction (see 
GpiSetCharDirection) and character shear (see GpiSetCharShear) attributes are set to their default 
values. 

This function is not valid when the drawing mode (see GpiSetDrawingMode) is set to retain. 
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Query Text Box 


Example Code 

This example uses the GpiQueryTextBox function to draw a line under the string. The GpiCharString 
function draws the string at the point (100,100). Since the points retrieved by GpiQueryTextBox are 
relative to the start of the string, the starting point needs to be added to the points that are used to 
draw the underline. 

Idefine INCL_GPIPRIMITIVES 
linclude <0S2.H> 

HPS hps; 

POINTL aptl [TXTB0X_C0UNT] ; 

POINTL ptl = { 100, 100 }; 

Gpi Query T extBox ( hps , 

11L, 

"This string", 

TXTB0X_C0UNT, /* return maximum information */ 
aptl); /* array of coordinates points */ 

/* in world coordinates. */ 

aptl [1] .x += ptl .x; 
aptl [1] .y += ptl .y; 

GpiMove(hps, &aptl[l]); 
aptl [3] .x += ptl .x; 
aptl [3] .y += ptl .y; 

GpiLine(hps, &aptl [3] ) ; 

Gpi Move (hps, &ptl); 

GpiCharString(hps, 11L, "This string"); 
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GpiQueryViewingLimits 
Query Viewing Limits 


#define INCL_GPITRANSFORMS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiQueryViewingLimits (HPS hps, PRECTL prcILImlts) 


This function returns the current value of the viewing limits, as set by the GpiSetViewingLimits 
function. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

prcILImlts (PRECTL) - output 
Viewing limits. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 

PMERRJNV HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_IN_RETAIN_MODE An attempt was made to issue a function (for example, 

query) that is invalid when the actual drawing mode is not 

draw or draw-and-retain. 

PMERR_INV_DC_TYPE An invalid type parameter was specified with 

DevOpenDC, or a function was issued that is invalid for a 
OD_METAFILE_NOQUERY device context. 


Remarks 

This function is invalid when the drawing mode (see GpiSetDrawingMode) is set to retain. 
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GpiQueryViewingLimits - 
Query Viewing Limits 


Example Code 

In this example the model space clipping region width is reduced to 100 if it is greater. 

Idefine INCL_GPITRANSFORMS 
linclude <0S2.H> 

HPS hps; /* Presentation-space */ 

/* handle. */ 

RECTL rcl Limits; /* viewing limits. */ 

BOOL f Success; 


fSuccess = GpiQueryViewingLimits(hps, 

&rcl Limits); 

if ((rclLimits.xRight - rclLimits.xLeft) > 100) 

{ 

rclLimits.xRight = 100; 
rclLimits.xLeft = 200; 

} 

fSuccess = GpiSetViewingLimits(hps, 

&rcl Limits) ; 
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GpiQueryViewingT ransformMatrix 
Query Viewing Transform Matrix 


#define INCL_GPITRANSFORMS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpIQueryVIewIngTransformMatrlx (HPS hps, LONG ICount, PMATRIXLF pmatlf Array) 


This function returns the current viewing transform (see GpiSetViewingTransformMatrix).. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

ICount (LONG) - input 
Number of elements. 

The number of elements to be returned in pmatlf Array (must be in the range 0 through 9). If 0 is 
specified, no matrix elements are returned. 

pmatlfArray (PMATRIXLF) - output 
Transform matrix. 

A structure in which the elements of the viewing transform matrix are returned. 

Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRJNVHPS 
PMERRPSBUSY 

PMERRINVMICROPSFUNCTION 

PMERR_INV_LENGTH_OR_COUNT 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An attempt was made to issue a function that is invalid in 
a micro presentation space. 

An invalid length or count parameter was specified. 
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Query Viewing Transform Matrix 


Example Code 

This example uses the GpiQueryViewingTransformMatrix function to see if the width and the height 
of drawing are already doubled. If this is not the case, the GpiSetViewingTransformMatrix is used to 
replace the existing viewing transformation. The new transformation will then double the width and 
height of drawing. 

Idefine INCL_GPITRANSFORMS 
Jinclude <0S2.H> 


HPS hps; /* Presentation space handle. */ 

LONG 1 Count; /* maximum number of elements */ 

MATRIXLF mat If = { MAKEFIXED(2,0) , /* scale x coordinates by a */ 

/* factor of 2. */ 

0, 0, 0, /* no rotation. */ 

MAKEFIXED(2,0) , /* scale y coordinates by a */ 

/* factor of 2. */ 

0, 0, 0, 1}; /* no rotation. */ 

ICount = 9L; /* number of elements. */ 

Gpi0ueryViewingTransformMatrix(hps, 

ICount, 

&matl f) ; 


if (matlf .fxM12 = MAKEFIXED(2, 0)) 

{ 

Gpi SetVi ewi ngTransformMatri x( hps , 

ICount, 

&matlf , 

TRANSF0RM_REPLACE) ; 


} 
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GpiQueryWidthTable - 
Query Font Width Table 


#define INCL_GPILCIDS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiQueryWidthTable (HPS hps, LONG IFirstChar, LONG ICount, PLONG aiData) 


This function returns width table information for the logical font identified by the value of the 
character-set attribute. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

IFirstChar (LONG) - input 

Codepoint of first character. 

The codepoint of the initial character, for which width-table information is required. 

ICount (LONG) - input 

Count of elements in aiData. 

The number that should be allowed for, so as to retrieve the full width table. Data for this font 
can be found by GpiQueryFontMetrics. 

aiData (PLONG) - output 
Array of width values. 

An array of ICount elements, in which width-table information is returned. No more than ICount 
elements are returned. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 


PMERRINVHPS 

PMERRPSBUSY 

PMERR_INV_FIRST_CHAR 

PMERR_INV_LENGTH_OR_COUNT 

PMERRCOORDINATEOVERFLOW 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid firstchar parameter was specified with 
GpiQueryWidthTable. 

An invalid length or count parameter was specified. 

An internal coordinate overflow error occurred. This can 
occur if coordinates or matrix transformation elements (or 
both) are invalid or too large. 
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GpiQueryWidthTable - 
Query Font Width Table 


Example Code 

In this example the widths of the first 50 characters of the current font are obtained. 

Idefine INCL_GPILCIDS 
linclude <0S2.H> 

Idefine COUNT 50 


HPS hps; /* Presentation-space */ 

/* handle. */ 

LONG al Data [COUNT] ; /* array of width values. */ 


GpiQueryWidthTable (hps, 

0 , 

COUNT, 
alData) ; 
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GpiRectlnRegion - 
Rectangle In Region 


#define INCL_GPIREGIONS /* Or use INCL_GPI or INCL_PM */ 


LONG GpiRectlnRegion (HPS hps, HRGN hrgn, PRECTL prcIRect) 


This function checks whether any part of a rectangle lies within the specified region. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

The region must be owned by the device identified by the currently associated device context. 

hrgn (HRGN) - input 
Region handle. 

prcIRect (PRECTL) - input 
Test rectangle. 

The rectangle is specified in device coordinates. 

Returns 

Inside and error indicators: 

RRGNOUTSIDE Not in region 
RRGN PARTIAL Some in region 
RRGNJNSIDE All in region 

RRGNERROR Error. 

Possible returns from WinGetLastError 

PMERR_INV_HPS 
PMERRPSBUSY 

PMERRINVHRGN 
PMERRINVCOORDINATE 
PMERR_INV_RECT 
PMERRREGIONJSCLIPREGION 

PMERRHRGNBUSY 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid region handle was specified. 

An invalid coordinate value was specified. 

An invalid rectangle parameter was specified. 

An attempt was made to perform a region operation on a 
region that is selected as a clip region. 

An internal region busy error was detected. The region 
was locked by one thread during an attempt to access it 
from another thread. 


Remarks 

It is invalid if the specified region is currently selected as the clip region (by GpiSetClipRegion). 
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GpiRectlnRegion - 
Rectangle In Region 


Related Functions 

• GpiCombineRegion 

• GpiCreateRegion 

• GpiDestroyRegion 

• GpiEqualRegion 

• GpiOffsetRegion 

• GpiPaintRegion 

• GpiPtlnRegion 

• GpiQueryRegionBox 

• GpiQueryRegionRects 

• GpiSetRegion 

Example Code 

In this example we check to see if a a rectangle is inside a region before we destroy the region. 

Idefine INCL_GPIREGIONS 
linclude <0S2.H> 

HPS hps; /* presentation-space handle. */ 

HRGN hrgn; /* region handle. */ 

PRECTL prclRect; /* test rectangle. */ 

LONG 1 Inside; /* result. */ 

llnside = GpiRectInRegion(hps, 

hrgn, 

prclRect); 

if (llnside = RRGN_OUTSIDE) 

{ 

GpiDestroyRegion (hps, hrgn); 

} 
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GpiRectVisible - 
Rectangle Visible 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


LONG GpiRectVisible (HPS bps, PRECTL prciRectangle) 


This function checks whether any part of a rectangle lies within the clipping region of the device 
associated with the specified presentation space. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

prciRectangle (PRECTL) - input 

Test rectangle, in world coordinates. 

Points on the borders of the rectangle are considered to be included within the rectangle. 

Returns 

Visibility indicator: 

RVISJNVISIBLE Not visible 

RVIS_PARTIAL Some of the rectangle is visible 

RVIS_VISIBLE All of the rectangle is visible 

RVIS_ERROR Error. 

Possible returns from WinGetLastError 

PMERRINVHPS 
PMERRPSBUSY 

PMERRINVCOORDINATE 
PMERR_INV_RECT 

Remarks 

For the purposes of this function, the clipping region is defined as the intersection between the 
application clipping region and any other clipping, including windowing. 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid coordinate value was specified. 

An invalid rectangle parameter was specified. 


Related Functions 

• GpiExcludeClipRectangle 

• GpilntersectClipRectangle 

• GpiOffsetClipRegion 

• GpiPtVisible 

• GpiQueryClipBox 

• GpiQueryClipRegion 

• GpiSetClipRegion 

• WinExcludellpdateRegion 
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GpiRectVisible - 
Rectangle Visible 


Example Code 

In this example the GpiRectVisible call is used to determine if all of the rectangle is visible. 

Idefine INCL_GPIPRIMITIVES 
linclude <0S2.H> 

HPS hps; /* presentation-space handle. */ 

LONG lVisibility; /* visibility indicator */ 

PRECTL pr cl Rectangle; /* test rectangle in world */ 

/* coordinates. */ 


lVisibility = Gpi RectVi si bl e (hps , 

prcl Rectangle) ; 

if (lVisibility = RVIS_INVISIBLE) /* rectangle is not */ 
{ /* visible. */ 

/* code block */ 

) 
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GpiRemoveDynamics 
Remove Dynamics 


#define INCL_GPISEGMENTS /* Or use INCL_GPI or INCL_PM 7 


BOOL GpiRemoveDynamics (HPS bps, LONG IFirstSegid, LONG ILastSegid) 


This function removes those parts of the displayed image that are drawn from the dynamic segments 
in a section of the segment chain. This includes any parts that are drawn by calls from these 
dynamic segments. 


Parameters 

bps (HPS) - input 

Presentation-space handle. 

IFirstSegid (LONG) - input 

First segment in the section. 

It must be greater than 0. 

ILastSegid (LONG) - input 

Last segment in the section. 

It must be greater than 0. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 


PMERR_INV_HPS 

PMERR_PS_BUSY 

PMERRINVMICROPSFUNCTION 

PMERRJNVSEGNAME 

PMERR_INV_FOR_THIS_DC_TYPE 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An attempt was made to issue a function that is invalid in 
a micro presentation space. 

An invalid segment identifier was specified. 

An attempt has been made to issue GpiRemoveDynamics 
or GpiDrawDynamics to a presentation space associated 
with a metafile device context. 


Remarks 

This function usually indicates that a dynamic segment is about to be updated; and that, having 
completed the update, GpiDrawDynamics is called to redraw the dynamic segments. 

If there is more than one dynamic segment, only those that are being updated need be removed. The 
section of the segment chain is identified by the first and last segments in the section. If IFirstSegid 
and ILastSegid have the same value, this call erases only the parts drawn from the segment, and by 
calls from that segment. 

Specifying the range of segment identifiers that are to be removed usually has a performance 
advantage, in that searching of the chain stops after ILastSegid has been processed. It can also be 
used to operate on less than the maximum number of dynamic segments, as in one of the following 
examples: 
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GpiRemoveDynamics - 
Remove Dynamics 


• Several dynamic segments are currently drawn, but only one is to be updated. Identifying this 
segment with both IFirstSegid and ILastSegid means that only this one is removed. It can then be 
updated, and replaced with GpiDrawDynamics. 

• A new dynamic segment can be created, while the rest remain drawn. GpiRemoveDynamics is 
issued before the segment has been created (or while it is unchained, if it already exists), 
identifying it with both IFirstSegid and ILastSegid. It is then created with this identifier (or 
chained, if it already exists), and GpiDrawDynamics is issued, causing it to be drawn. 

In these examples, the other dynamic segments remain drawn throughout. 

In all cases, after GpiDrawChain, GpiDrawDynamics, GpiDrawFrom, or GpiDrawSegment, where the 
DCTL_DYNAMIC draw control is set (see GpiSetDrawControl), all dynamic segments must be drawn. 
The IFirstSegid and ILastSegid parameters of GpiRemoveDynamics, cannot be used to cause a 
subset of dynamic segments to be drawn after the following GpiDrawDynamics. If this is required, it 
can be done by unchaining the unwanted dynamic segments after first removing them. 

Dynamic segments that are currently drawn must never be updated in the segment store, nor must 
any drawing in mix modes (other than exclusive-OR or leave-alone) be done to a presentation space 
while dynamic segments are drawn in it. 

If a temporary re-association is to be done, this function must be issued to remove the dynamic 
segments from the display before the first dissociation. 

It Is necessary to ensure that attributes, model transform, current position, and viewing limits are 
reset to their default values, before processing the segments. This can either be done by ensuring 
that the first dynamic segment in the removed section does not have the ATTR_FASTCHAIN attribute 
(see GpiSetlnitialSegmentAttrs), or by issuing GpiResetPS before the GpiRemoveDynamics. The 
latter method also resets the clip path to cause no clipping, which may also be necessary. 

If this function is followed by primitives or attributes, without first opening a segment, the processing 
is as described for GpiCloseSegment. In particular, note that during GpiRemoveDynamics, the 
system forces the foreground mix to FM XOR and the background mix to BM_LEAVEALONE. It may 
be necessary to set one or both of these before starting to draw. 

If IFirstSegid does not exist, or is not in the segment chain, no removal or drawing occurs. However, 
the segment identifier range is still established for a subsequent GpiDrawDynamics function. 

If ILastSegid does not exist, or is not in the chain, or is chained before IFirstSegid, no error is raised, 
and processing continues to the end of the chain. 


Related Functions 

• GpiDrawChain 

• GpiDrawDynamics 

• GpiDrawFrom 

• GpiDrawSegment 

• GpiErase 

• GpiGetData 

• GpiPutData 

• GpiSetDrawControl 

• GpiSetDrawingMode 

• GpiSetStopDraw 
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GpiRemoveDynamics 
Remove Dynamics 


Example Code 

This example uses the GpiRemoveDynamics function to remove the image drawn by the dynamic 
segment whose segment identifier is 4. It then edits the segment and redraws it, using the 
GpiDrawDynamics function. 

Idefine INCL_GPISEGMENTS 
Idefine INCL_GPICONTROL 
linclude <0S2.H> 


POINTL ptl = {30, 40}; 

HPS hps; /* presentation space handle */ 

/* Remove the image for dynamic segment #4. */ 

GpiRemoveDynamics (hps, 4L, 4L); 

/* Edit the segment. */ 

GpiSetDrawi ngMode(hps.DMRETAIN) ; 

GpiOpenSegment(hps, 4L); 

GpiSetElementPointer(hps, 1L); 

Gpi Move (hps, &ptl); 

GpiCloseSegment(hps) ; 

GpiDrawDynamics (hps) ; /* redraws the edited segment */ 
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GpiResetBoundaryData - 
Reset Boundary Data 


#define INCL_GPICORRELATION /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiResetBoundaryData (HPS hps) 


This function resets the boundary data to null. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERR_INV_HPS An invalid presentation-space handle was specified. 

PMERR PS BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

Remarks 

This function is only necessary for draw mode (see GpiSetDrawingMode) boundary determination. 
Boundary data is automatically reset before any retained drawing call. 

After drawing, boundary data can be found by issuing GpiQueryBoundaryData. 

Note: Boundary data is not reset at the start of a segment. 

Related Functions 

• GpiQueryBoundaryData 

• GpiSetDrawControl 

Example Code 

This function is used to reset the boundary data to null. It is only necessary for draw mode boundary 
determination. 

Idefine INCL_GPICORRELATION 
linclude <0S2.H> 

HPS hps; /* presentation space handle */ 

GpiResetBoundaryData (hps) ; 
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GpiResetPS - 

Reset Presentation Space 


#define INCL_GPICONTROL /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiResetPS (HPS hps, ULONG flOptlons) 


This function resets the presentation space. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

flOptlons (ULONG) - input 
Reset option: 

GRES_ATTRS 

This has the following effects: 

• All current attributes and arc parameters are reset to their default values 

• The current tag is reset to its default value 

• The current model transform is reset to unity 

• The current position is set to (0,0) 

• Any open path or area is aborted 

• Any open element bracket is closed 

• Any open segment is closed 

• The current clip path is set so as to cause no clipping 

• The current viewing limits are reset to their default values. 

GRES_SEGMENTS 

This has all the effects of GRES_ATTRS plus: 

• Any retained segments are deleted 

• Initial segment attributes are reset to their default values 

• The default viewing transform and the graphics field are reset to their default values 

• The viewing transform is set to unity 

• Drawing mode, draw controls, edit mode and attribute mode are reset to default values 

• Boundary data is reset 

• The currently selected clip region, if any, is deselected, and destroyed 

• The default values of primitive attributes, arc parameters, viewing limits and primitive 
tag are reset to their initial values. 

GRES_ALL 

This has all the effects of GRES_ATTRS and GRES_SEGMENTS plus: 

• Any logical fonts and local identifiers for bit maps are deleted (the default character set 
is restored if it has been changed). 

• Any loaded logical color table is reset to default. 

• Any palette selected into the presentation space (see GpiSelectPalette) is deselected. 

• The pick aperture size and position are reset to default. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 
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GpiResetPS - 
Reset Presentation Space 


Possible returns from WinGetLastError 

PMERR_INV_HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_RESET_OPTIONS An invalid options parameter was specified with 

GpiResetPS. 


Remarks 

Three levels of reset are provided. These are, in increasing order of power: 

• As if a new (root) segment is being processed 

• As if the presentation space is being created without deleting resources 

• As if the presentation space is being created with resources deleted. 

More details are provided under the description of flOptions above. 

None of these options cause any drawing or erasing to take place on the device (GpiErase can be 
used to do the latter), nor is any association between the specified presentation space and a device 
context affected. The page viewport is also unaffected. 

After restoring a presentation space that has a palette selected into it, WinRealizePalette must be 
issued before any drawing calls or calls to query colors. 

Note: This function must not be used when creating SAA-conforming metafiles; see “Metafile 
Restrictions” on page G-1. 

Related Functions 

• GpiAssociate 

• GpiCreatePS 

• GpiDestroyPS 

• GpiQueryDevice 

• GpiQueryPS 

• GpiRestorePS 

• GpiSavePS 

• GpiSetPS 

Example Code 

This function is used to reset the presentation space. 

Idefine INCL_GPICONTROL 
linclude <0S2.H> 

HPS hps; /* presentation space handle */ 

ULONG flOptions; /* reset options */ 

flOptions = GRES_ALL; /* reset all options. */ 

GpiResetPS (hps, flOptions); 
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GpiRestorePS - 
Restore Presentation Space 


#define INCL_GPICONTROL /* Or use INCL_GPI or INCL_PM. Also in COMMON section */ 


BOOL GpiRestorePS (HPS hps, LONG IPSid) 


This function restores the state of the presentation space to the one that exists when the 
corresponding GpiSavePS is issued. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

IPSid (LONG) - input 

Identifier of the saved presentation space that is to be restored: 

If an error is returned, the stack is unchanged, as is the current presentation space. 

>0 IPSid must be the identifier of a saved presentation space on the stack. It is an error if it 
does not exist. 

0 Is an error. (This might have resulted from an invalid use of GpiSavePS). 

<0 The absolute value of IPSid indicates how many saved presentation spaces on the stack 
are required. Thus -1 means that the most recently saved one is to be restored. It is an 
error if the absolute value is larger than the number of entries on the stack. 

Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRJNV HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_NOT_IN_DRAW_MODE An attempt was made to issue GpiSavePS or 

GpiRestorePS while the drawing mode was not set to 
DM_DRAW. 

PMERRJNVJD An invalid IPSid parameter was specified with 

GpiRestorePS. 


Remarks 

The most recently saved presentation space need not be the one that is restored. In this case, any 
that are skipped over on the stack are discarded. 

Any clip regions selected into discarded presentation spaces are automatically destroyed. 

This function is valid in an open element bracket and in an open segment bracket if the drawing 
mode (see GpiSetDrawingMode) is set to draw and within an open element bracket. If it occurs 
within an open area or path bracket, the corresponding GpiSavePS must have taken place earlier in 
the same bracket. 
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GpiRestorePS - 
Restore Presentation Space 


Related Functions 

• GpiAssociate 

• GpiCreatePS 

• GpiDestroyPS 

• GpiQueryDevice 

• GpiQueryPS 

• GpiResetPS 

• GpiSavePS 

• GpiSetPS 

• GpiPop 

Example Code 

This example restores the state of the presentation space to the one that exists when the 
corresponding GpiSavePS is issued. 

Idefine INCL_GPICONTROL 
linclude <0S2.H> 

HPS hps; /* presentation space handle */ 

LONG IPSid; /* the identifier of a saved presentation */ 

/* space on the stack. */ 

GpiRestorePS (hps, IPSid); 
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G pi Rotate - 
Rotate Transform 


#define INCL_GPITRANSFORMS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiRotate (HPS hps, PMATRIXLF pmatlf Array, LONG lOptlons, FIXED fxAngle, 
PPOINTL pptICenter) 


This function applies a rotation to a transform matrix. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

pmatlfArray (PMATRIXLF) - input/output 
Transform matrix. 

The elements of the transform, in row order. The first, second, fourth, and fifth elements are of 
type FIXED, and have an assumed binary point between the second and third bytes. Thus a 
value of 1.0 is represented by 65 536. Other elements are normal signed integers. 

The third, sixth, and ninth elements must be 0, 0, and 1, respectively. 

lOptlons (LONG) - input 
Transform options. 

Specifies how the transform defined by the specified rotation should be used to modify the 
previous transform specified by the pmatlfArray parameter. Possible values are: 

TRANSFORM_REPLACE The previous transform is discarded and replaced by the transform 

describing the specified rotation. 

TRANSFORM_ADD The previous transform is combined with a transform representing 

the specified rotation in the order (1) previous transform, (2) 
rotational transform. This option is most useful for incremental 
updates to transforms. 

fxAngle (FIXED) - input 
Rotation angle. 

The angle describing the rotation, measured counterclockwise from the x-axis in degrees. 

pptICenter (PPOINTL) - input 
Center of rotation. 

The point about which the rotation occurs. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERR INV TRANSFORM TYPE An invalid options parameter was specified with a 

transform matrix function. 
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Gpi Rotate - 
Rotate Transform 


Remarks 

This function is a helper function that either applies a specified rotational component to an existing 
transform matrix, or replaces the matrix with one that represents the specified rotation alone. 

The transform is specified as a one-dimensional array of 9 elements that are the elements of a 3-row 
by 3-column matrix ordered by rows. The order of the elements is as follows: 

Matrix Array 


a b 0 
c d 0 
e f 1 


(a,b,0,c,d,0,e,f, 1) 


Transforms act on the coordinates of primitives, so that a point with coordinates (x,y) is transformed 
to the point: 

(a*x + c*y + e, b*x + d*y + f) 

The transform can be used in any call following: 

• GpiSetModelTransformMatrix 

• GpiSetSegmentTransformMatrix 

• GpiSetViewingTransformMatrix 

• GpiSetDefauitViewMatrix. 

Other similar helper functions are: 

• GpiTranslate to apply a translation component 

• GpiScale to apply a scaling component. 


Related Functions 

• GpiScale 

• GpiTranslate 

• GpiSetModelTransformMatrix 

• GpiSetSegmentTransformMatrix 

• GpiSetDefauitViewMatrix 

• GpiSetViewingTransformMatrix 
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Gpi Rotate - 
Rotate Transform 

Example Code 

In this example, the viewing transform matrix is rotated 10 degrees counterclockwise from the x-axis. 
Hence, everything will appear rotated. 

Idefine INCL_GPITRANSFORMS 
linclude <0S2.H> 


HPS hps; /* presentation space handle */ 
MATRIXLF matlf; /* transform matrix. */ 
POINTL ptl Center; /* center of rotation. */ 


Gpi QueryVi ewi ngT ransformMatri x( hps , 

1L, 

&matlf) ; 

ptlCenter.x = 50L; 

ptl Center. y = 50L; 

Gpi Rotate (hps, 

&matl f , 

TRANSFORM_REPLACE, 

MAKEFIXED(10,0) , /* rotate 10 degrees left, the angle */ 

/* must be passed in fixed format. */ 

/* see the pmgpi.h file for a */ 

/* description of the MAKEFIXED macro. */ 

&ptl Center); 
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GpiSaveMetaFile - 
Save Metafile 


#define INCL_GPIMETAFILES /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSaveMetaFile (HMF hmf, PSZ pszFilename) 


This function saves a metafile in a disk file. 


Parameters 

hmf (HMF) - input 
Metafile handle. 

pszFilename (PSZ) - input 
File name. 

The name of the file to which the metafile is to be saved. This name must be a valid external 
name. 

It is an error if a file of this name exists already. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 


PMERRINVHMF 


An invalid metafile handle was specified. 


PMERR_DOSOPEN_FAILURE A DosOpen call made during GpiLoadMetaFile or 

GpiSaveMetaFile gave a good return code but the file was 
not opened successfully. 

PMERR_INSUFFICIENT_DISK_SPACE The operation terminated through insufficient disk space. 


PMERR_MET AFILE _IN_USE 


An attempt has been made to access a metafile that is in 
use by another thread. 


PMERR_TOO_MANY_METAFILES_IN_USE The maximum number of metafiles allowed for a given 

process was exceeded. 


Remarks 

The metafile is deleted from storage; this means that the metafile handle is no longer valid. 
The metafile may be reaccessed by GpiLoadMetaFile. 


Related Functions 

• GpiCopyMetaFile 

• GpiDeleteMetaFile 

• GpiLoadMetaFile 

• GpiPlayMetaFile 

• GpiQueryMetaFileBits 

• GpiQueryMetaFileLength 

• GpiSetMetaFileBits 
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GpiSaveMetaFile 
Save Metafile 


Example Code 

This function saves a metafile in a disk file. 

Idefine INCL_GPIMETAFILES 
finclude <0S2.H> 

HMF hmf; /* metafile handle. */ 
GpiSaveMetaFile(hmf , “fil e.met") ; 
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GpiSavePS - 
Save Presentation Space 


#define INCL_GPICONTROL /* Or use INCL_GPI or INCL_PM. Also in COMMON section */ 


LONG GpiSavePS (HPS hps) 


This function saves information about the presentation space on a LIFO (last in, first out) stack. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 


Returns 

Identifier of saved presentation space. 

This may be used on a subsequent GpiRestorePS call. The identifier is equal to the depth of the 
saved presentation space on the save/restore stack, with 1 representing the base level: 

>1 Identifier of saved presentation space 

GPI_ERROR Error. 


Possible returns from WinGetLastError 

PMERR_INV_HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_NOT_IN_DRAW_MODE An attempt was made to issue GpiSavePS or 

GpiRestorePS while the drawing mode was not set to 
DM_DRAW. 


Remarks 

The stack is different from the one used to save attribute values (see GpiSetAttrMode) in a normal 
presentation space. 

This function, and GpiRestorePS, can be used with a micro presentation space, as well as a normal 
presentation space (in draw drawing mode only). 

The presentation space itself is unchanged. 

The following are saved: 

• Current attributes 

• Current transforms, viewing limits, and clip path 

• Current position 

• Reference to selected clip region 

• Any loaded logical color table 

• References to any loaded logical fonts 

• References to the regions created on the associated device context. 

The following are not saved: 

• Draw controls 

• Drawing mode 

• Edit mode and attribute mode 

• The visible region. 
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GpiSavePS - 

Save Presentation Space 


Note: Only references to resources, rather than the actual resources (such as clip region, logical 
fonts, and regions) are copied by this function, so the actual resources must not be changed. 

This function is valid in an open segment bracket, but only if the drawing mode (see 
GpiSetDrawingMode) is set to draw. This function can occur within an open element bracket. When 
it occurs within an open area or path bracket, GpiRestorePS must be called before the bracket is 
closed. 

If this function occurs during the generation of a metafile, the drawing mode must be set to draw 
when the metafile is replayed. 


Related Functions 

• GpiAssociate 

• GpiCreatePS 

• GpiDestroyPS 

• GpiQueryDevice 

• GpiQueryPS 

• GpiResetPS 

• GpiRestorePS 

• GpiSetPS 

Example Code 

This example uses the GpiSavePS function to save the state of the presentation space. The identifier 
returned by the function is used in the call to the GpiRestorePS function to restore the saved state. 

Idefine INCL_GPICONTROL 
finclude <0S2.H> 

HPS hps; /* presentation-space handle. */ 

LONG idPS; 

idPS = GpiSavePS(hps) ; /* saves the presentation-space state */ 


/* restores the presentation-space state */ 
GpiRestorePS(hps, idPS); 


5-392 


PM Programming Reference 



GpiScale - 
Scale Matrix 


#define INCLJ3PITRANSF0RMS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiScale (HPS hps, PMATRIXLF pmatifArray, LONG lOptlons, PFIXED afxScale, 
PPOINTL pptiCenter) 


This function applies a scaling component to a transform matrix. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

pmatifArray (PMATRIXLF) - input/output 
Transform matrix. 

The elements of the transform, in row order. The first, second, fourth, and fifth elements are of 
type FIXED, and have an assumed binary point between the second and third bytes. Thus a 
value of 1.0 is represented by 65 536. Other elements are normal signed integers. 

The third, sixth, and ninth elements must be 0, 0, and 1, respectively. 

lOptlons (LONG) - input 
Transform options. 

Specifies how the transform defined by the specified scaling should be used to modify the 
previous transform specified by the pmatifArray parameter. Possible values are: 

TRANSFORM_REPLACE The previous transform is discarded and replaced by the transform 

describing the specified scaling. 

TRANSFORM_ADD The previous transform is combined with a transform representing 

the specified scaling in the order (1) previous transform, (2) scaling 
transform. This option is most useful for incremental updates to 
transforms. 

afxScale (PFIXED) - input 
Scale factors. 

The first element of the array is the x scale factor, and the second is the y scale factor. 

Scaling values outside the range -1 through + 1 are not valid for subsequent use with 
presentation spaces that have a coordinate format (as set by the GpiCreatePS function) of 
GPIF_SHORT. 

pptiCenter (PPOINTL) - input 
Center of scale. 

The point about which the scale occurs. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRJNV TRANSFORM TYPE An invalid options parameter was specified with a 

transform matrix function. 
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GpiScale - 
Scale Matrix 


Remarks 

This function is a helper function which either applies a specified scaling component to an existing 
transform matrix, or replaces the matrix with one that represents the specified scaling alone. 

The transform is specified as a one-dimensional array of 9 elements that are the elements of a 3-row 
by 3-column matrix ordered by rows. The order of the elements is: 

Matrix Array 


a b 0 
c d 0 
e f 1 


(a,b,0,c,d,O,e,f ,1) 


Transforms act on the coordinates of primitives, so that a point with coordinates (x,y) is transformed 
to the point: 

(a*x + c*y + e, b*x + d*y + f) 

The transform can be used in any call following: 

• GpiSetModelTransformMatrix 

• GpiSetSegmentTransformMatrix 

• GpiSetViewingTransformMatrix 

• GpiSetDefauitViewMatrix. 

Other similar helper functions are: 

• GpiTranslate to apply a translation component 

• Gpi Rotate to apply a rotation component. 


Related Functions 

• Gpi Rotate 

• GpiTranslate 

• GpiSetModelTransformMatrix 

• GpiSetSegmentTransformMatrix 

• GpiSetDefauitViewMatrix 

• GpiSetViewingTransformMatrix 
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GpiScale - 
Scale Matrix 


Example Code 

In this example, the viewing transform matrix is scaled by a factor of 2. 

Idefine INCL.GPITRANSFORMS 
linclude <0S2.H> 

HPS hps; /* presentation space handle */ 

MATRIXLF matlf; /* transform matrix. */ 

POINTL ptlCenter; /* center of rotation. */ 


Gpi Query Vi ewi ngT ransformMatri x (hps , 

1L, 

Umatlf) ; 

ptl Center. x = 50L; 

ptlCenter.y = 50L; 

GpiRotate(hps, 

&matlf, 

TRANSFORM_REPLACE, 

MAKEFIXED(2,0) , /* rotate 10 degrees left, the angle */ 
/* must be passed in fixed format. */ 
/* see the pmgpi.h file for a */ 

/* description of the MAKEFIXED macro. */ 

&ptl Center) ; 
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GpiSelectPalette 
Select Palette 


#define INCL_GPILOGCOLORTABLE /* Or use INCL_GPI or INCL_PM */ 


HPAL GpiSelectPalette (HPS hps, HPAL hpal) 


This function selects a palette into a presentation space. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

hpal (HPAL) - input 
Palette handle. 

NULLHANDLE Set the color table for the presentation space to the default table (see 
GpiCreateLogColorTable). 

Other Palette handle. 


Returns 

Old palette handle: 

NULLHANDLE Successful completion, default (or loaded) color table was in effect 
PAL_ERROR Error occurred 
Otherwise Old palette handle. 


Possible returns from WinGetLastError 


PMERRINVHPS 

PMERRPSBUSY 

PMERRINVHPAL 

PMERRINSUFFICIENTMEMORY 

PMERR_PALETTE_BUSY 

PMERRINVINAREA 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid color palette handle was specified. 

The operation terminated through insufficient memory. 

An attempt has been made to reset the owner of a palette 
when it was busy. 

An attempt was made to issue a function invalid inside an 
area bracket. This can be detected while the actual 
drawing mode is draw or draw-and-retaln or during 
segment drawing or correlation functions. 


Remarks 

This function overrides any color table previously loaded (see GpiCreateLogColorTable), or palette 
previously selected into this presentation space. 

If hpal is specified as NULLHANDLE, then the color table for this presentation space is set to the 
default color table. 

Palettes can be selected into more than one presentation space at a time, but only one palette can be 
selected into a given presentation space at any time. 

If a palette is selected into a presentation space that is associated with a device context of type 
ODMEMORY (see DevOpenDC), irreversible changes take place to any bit map selected into the 
device context. 
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GpiSelectPalette - 
Select Palette 


If a palette is selected into a presentation space that is associated with a device context of type 
OD METAFILE or OD_METAFILE_NOQUERY, the palette must apply to the entire picture, and must 
still be selected at the (last) time the metafile device context is dissociated from the presentation 
space. 

Related Functions 

• GpiAnimatePalette 

• GpiCreatePalette 

• GpiCreateLogColorTable 

• GpiDeletePalette 

• GpiQueryPalette 

• GpiQueryPalettelnfo 

• GpiSetPaletteEntries 

• WinRealizePalette 

Example Code 

This function selects a palette into a presentation space. 

Idefine INCL_GPILOGCOLORTABLE 
linclude <0S2.H> 

HPS hps; /* presentation-space handle. */ 

HPAL hpalOld, hpal ; /* old palette handle. */ 

hpalOld = GpiSelectPalette(hps, hpal); 
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GpiSetArcParams - 
Set Arc Parameters 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetArcParams (HPS hps, PARCPARAMS parcpArcParams) 


This function sets the current arc parameters. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

parcpArcParams (PARCPARAMS) - input 
Arc parameters. 

This structure has four elements p, q, r, and s. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRJNV HPS An invalid presentation-space handle was specified. 

PM£RR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_COORDINATE An invalid coordinate value was specified. 

Remarks 

The arc parameters p, q, r, and s, define the shape and orientation of a ellipse that is used for 
subsequent GpiPointArc, GpiFullArc, and GpiPartialArc functions. For GpiFullArc and GpiPartialArc, 
they also determine the direction of drawing, as follows: 

• If p*q > r*s the direction is counterclockwise 

• If p*q < r*s the direction is clockwise 

• If p*q = r*s a straight line is drawn. 



Figure 5-5. GpiSetArcParams Coordinate Points 

For GpiFullArc and GpiPartialArc, these parameters also define the nominal size of the ellipse; this 
may be changed by using the multiplier. 
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GpiSetArcParams - 
Set Arc Parameters 


For GpiPointArc, the size of the ellipse is determined by the three points specified on GpiPointArc. 

The arc parameters define a transformation that maps the unit circle to the required ellipse, placed 
at the origin (0,0): 

x 1 = p*x + r*y 
y 1 = s*x + q*y 

With reference to Figure 5-5 on page 5-398, if p*r + s*q = 0, the transform is termed orthogonal, and 
the line from the origin (0,0) to the point (p,s) is either the radius of the circle, or half the major axis 
of the ellipse. The line from the origin tothe point (r,q) is either the radius of the circle, or half of the 
minor axis of the ellipse. 

For maximum accuracy, orthogonal transforms must be used. The matrix must not be singular. 

The initial default values of arc parameters (unless changed with GpiSetDefArcParams) are: 

p = 1 r = 0 
s = 0 q = 1 

producing a unit circle. (See Figure 5-6). 

T (0.1) 


( 0 . 0 ) 


( 1 . 0 ) 


Figure 5-6. GpiSetArcParams Default Coordinates 

Arc parameter transformation takes place in world coordinates. Any other non-square 
transformations in force change the shape of the figure accordingly. 

The attribute mode (see GpiSetAttrMode) determines whether the current value of the arc 
parameters is preserved. 


Related Functions 

• GpiQueryArcParams 

• GpiSetDefArcParams 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiSetBackColor 

• GpiSetBackMix 

• GpiSetColor 

• GpiSetMix 

• GpiSetLineType 

• GpiSetLineWidth 

• GpiFullArc 

• GpiPartialArc 

• GpiPointArc 
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GpiSetArcParams - 
Set Arc Parameters 


Graphic Elements and Orders 

Element Type: OCODE_GSAP 

This element type is generated if the attribute mode (see GpiSetAttrMode) is set to 
AM_NOPRESERVE. 

Order: Set Arc Parameters 

Element Type: OCODE_GPSAP 

This element type is generated if the attribute mode is set to AM_PRESERVE. 

Order: Push and Set Arc Parameters 

Example Code 

This example uses the GpiSetArcParams function to draw an ellipse. The semimajor axis of the 
ellipse is 100, and the semiminor axis is 50. These values are in world coordinates, computed using 
the IP and IQ values of the arc parameters and the multiplier provided with the GpiFullArc function. 

Idefine INCL_GPIPRIMITIVES 
linclude <0S2.H> 

HPS hps; 

ARC PAR AMS arcp = { 4, 2, 0, 0 }; 


POINTL ptl = {100, 100}; 

Gpi SetArcParams (hps , &arcp) ; 

GpiMove(hps, &ptl); 

Gpi Full Arc (hps, DR0_0UTLINE, MAKEFIXED (25 , 0)); 


/* Presentation-space */ 

/* handle. */ 

/* Arc parameters. */ 

/* This structure has four */ 
/* elements p, q, r, and s. */ 
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GpiSetAttrMode - 
Set Attribute Mode 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetAttrMode (HPS hps, LONG IMode) 


This function specifies the current attribute mode. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

IMode (LONG) - input 
Attribute mode: 

AM_PRESERVE Preserve attributes 
AM_NOPRESERVE Do not preserve attributes. 

Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRINVHPS 
PMERR_PS_BUSY 

PMERRJNVATTRMODE 

PMERRINVMICROPSFUNCTION 

P M E R R_IN V_DC_TYPE 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid mode parameter was specified with 
GpiSetAttrMode. 

An attempt was made to issue a function that is invalid in 
a micro presentation space. 

An invalid type parameter was specified with 
DevOpenDC, or a function was issued that is invalid for a 
OD_METAFILE_NOQUERY device context. 


Remarks 

The attribute mode is used to specify whether a primitive attribute is to be preserved when set to a 
new value by a subsequent attribute setting call. The preserved value of an attribute can be restored 
using the GpiPop function. Any attributes that have been preserved in a called segment are 
automatically restored on return to the caller. The values of any attributes preserved in a chained 
segment, however, that are not restored using GpiPop by the end of the segment, are lost. 

The following are affected: 

• GpiSetArcParams 

• GpiSetBackColor (applies individually by primitive type if GpiSetAttrs is used) 

• GpiSetBackMix (applies individually by primitive type if GpiSetAttrs is used) 

• GpiSetCharAngle 

• GpiSetCharBox 

• GpiSetCharDirection 

• GpiSetCharMode 

• GpiSetCharSet 

• GpiSetCharShear 
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• GpiSetColor (applies individually by primitive type if GpiSetAttrs is used) 

• GpiSetCurrentPosition 

• GpiSetMix (applies individually by primitive type if GpiSetAttrs is used) 

• GpiSetLineEnd 

• GpiSetLineJoin 

• GpiSetLineType 

• GpiSetLineWidth 

• GpiSetLineWidthGeom 

• GpiSetMarkerBox 

• GpiSetMarkerSet 

• GpiSetMarker 

• GpiSetModelTransformMatrix 

• GpiSetPattern 

• GpiSetPatternRefPoint 

• GpiSetPatternSet 

• GpiSetTag. 

The initial value of the attribute mode, that is, its value before this function is issued, is 
AM_NOPRESERVE. 

Attribute mode applies to attributes passed across the API using GpiSet... calls. What mode to use 
for a particular GpiSet... call is decided by the attribute mode current at the time the GpiSet... call is 
passed across the API. The mode may be changed at any time, and does not affect any attribute 
setting calls that have already been retained in the segment store. 

Attribute mode only applies to individual GpiSet... calls (including GpiSetAttrs and calls such as 
GpiSetColor). It does not apply to any attribute setting calls passed across in bulk, such as 
GpiPutData, GpiElement, and GpiPlayMetaFile; these already indicate individually whether they 
should cause the attribute to be preserved. 

Attribute mode cannot be set for GPIT_MICRO type presentation spaces, or for presentation spaces 
associated with OD_METAFILE_NOQUERY type device contexts (see GpiCreatePS and DevOpenDC). 
In these cases the presentation space behaves as if AM_NOPRESERVE is in operation. 


Related Functions 

• GpiPop 

• GpiQueryAttrMode 

• GpiResetPS 

• GpiQueryAttrs 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiSetPS 
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Example Code 

This example uses the GpiSetAttrMode function to set the attribute mode to preserve. 


Idefine INCL_GPIPRIMITIVES 
finclude <0S2.H> 

HPS hps; /* Presentation-space*/ 

/* handle. */ 

POINTL ptl [2] = { 50, 50, 100, .100, }; 

GpiSetColor(hps, CLR_BLUE); 

GpiSetAttrMode (hps, AM_PRESERVE) ;/* sets attribute mode to */ 

/* preserve. */ 

GpiSetColor(hps, CLR_GREEN); /* changes color and saves old */ 

/* color. */ 

GpiLine(hps, &ptl [0] ) ; /* draws green line */ 

GpiPop(hps, 1L); /* pops old attribute from */ 

/* stack. */ 

Gpi Line(hps, &ptl [1] ) ; /* draws blue line */ 
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#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM 7 


BOOL GpiSetAttrs (HPS hps, LONG IPrimType, ULONG fiAttrMask, ULONG flOefMask, 
PBUNOLE ppbunAttrs) 


This function sets attributes for the specified primitive type. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

IPrimType (LONG) - input 
Primitive type. 


The primitive type for which attributes are to be set: 


PRIMJJNE 
PRIMCHAR 
PRIMMARKER 
PRIMAREA 
PRIM IMAGE 


Line and arc primitives 
Character primitives 
Marker primitives 
Area primitives 
Image primitives. 


fiAttrMask (ULONG) - input 


Attributes mask. 

Each flag set indicates that either the corresponding flag in fIDefMask is set, or the ppbunAttrs 
buffer contains data for the corresponding attribute. If all of the flags in fiAttrMask are 0, the 
ppbunAttrs buffer address is not used. 

Line attributes: 


LBB_COLOR 

Line color 

LBBMIXMODE 

Line mix 

LBB_ WIDTH 

Line width 

LBB_GEOM_ WIDTH 

Geometric line width 

LBB_TYPE 

Line type 

LBBEND 

Line end 

LBBJOIN 

Line join. 

Character attributes: 

CBB_COLOR 

Character color 

CBBBACKCOLOR 

Character background color 

CBBMIXMODE 

Character mix 

CBBBACKMIXMODE 

Character background mix 

CBBSET 

Character set 

CBBMODE 

Character mode 

CBBBOX 

Character box 

CBBANGLE 

Character angle 
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CBB_SHEAR 

CBBDIRECTION 

Marker attributes: 

MBB_COLOR 

MBBBACKCOLOR 

MBBMIXMODE 

MBBBACKMIXMODE 

MBBSET 

MBBSYMBOL 

MBBBOX 


Character shear 
Character direction 

Marker color 

Marker background color 

Marker mix 

Marker background mix 
Marker set 
Marker symbol 
Marker box. 


Pattern attributes (areas): 

ABB.COLOR 

ABBBACKCOLOR 

ABBMIXMODE 

ABB_BACK_MIX_MODE 

ABBSET 

ABBSYMBOL 

ABB REF POINT 


Area color 

Area background color 
Area mix 

Area background mix 
Pattern set 
Pattern symbol 
Pattern reference point. 


Image attributes: 

IBB_COLOR Image color 

IBB_BACK_COLOR Image background color 

IBB_MIX_MODE Image mix 

IBB_BACK_MIX_MODE Image background mix. 

fiDefMask (ULONG) - input 
Defaults mask. 

Each flag set (and for which flAttrMask is also set) causes the corresponding attribute to be set 
to its default value. 


ppbunAttrs (PBUNDLE) - input 
Attributes. 


This is a structure containing the attribute value of each attribute for which the flAttrMask flag is 
set (and which is not to be set to its default value), at the correct offset as specified below for the 
particular primitive type. 


Primitive type: 

Line attributes 
Character attributes 
Marker attributes 
Pattern attributes (areas) 
Image attributes 


Structure: 

LINEBUNDLE 

CHARBUNDLE 

MARKERBUNDLE 

AREABUNDLE 

IMAGEBUNDLE. 
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Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 


PMERRINVHPS 

PMERRPSBUSY 

PM ERR_INV_PRIMITIVE_TYPE 

PMERR_UNSUPPORTED_ATTR 

P M E R R_IN V_COLOR_ATTR 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid primitive type parameter was specified with 
GpiSetAttrs or GpiQueryAttrs. 

An unsupported attribute was specified in the attrmask 
with GpiSetAttrs or GpiQueryAttrs. 

An invalid color attribute value was specified or the 
default value was explicitly specified with GpiSetAttrs 
instead of using the defaults mask. 


PMERR_INV_BACKGROUND_COL_ATTR An invalid background color attribute value was specified 

or the default value was explicitly specified with 
GpiSetAttrs instead of using the defaults mask. 


PMERR_INV_MIX_ATTR An invalid mix attribute value was specified or the default 

value was explicitly specified with GpiSetAttrs instead of 
using the defaults mask. 


PMERR_INV_LIN E_WIDTH_ ATTR 

PMERR_INV_GEOM_LINE_WIDTH_ATTR 

PMERRJNV_LINE_TYPE_ATTR 

PMERR_INV_LINE_END_ATTR 

PMERRJNVLINEJOINATTR 

PMERR_INV_CHAR_SET_ATTR 

PMERR_INV_CHAR_MODE_ATTR 


An invalid line width attribute value was specified or the 
default value was explicitly specified with GpiSetAttrs 
instead of using the defaults mask. 

An invalid geometric line width attribute value was 
specified. 

An invalid line type attribute value was specified or the 
default value was explicitly specified with GpiSetAttrs 
instead of using the defaults mask. 

An invalid line end attribute value was specified. 

An invalid line join attribute value was specified. 

An invalid character setid attribute value was specified or 
the default value was explicitly specified with GpiSetAttrs 
instead of using the defaults mask. 

An invalid character mode attribute value was specified 
or the default value was explicitly specified with 
GpiSetAttrs instead of using the defaults mask. 


PMERR INV_CHAR DIRECTION_ATTR An invalid character direction attribute value was 

specified or the default value was explicitly specified with 
GpiSetAttrs instead of using the defaults mask. 


PMERR_INV_CHAR_SHEAR_ATTR An invalid character shear attribute value was specified 

or the default value was explicitly specified with 
GpiSetAttrs instead of using the defaults mask. 

PMERR_INV_CHAR_ANGLE_ATTR The default character angle attribute value was explicitly 

specified with GpiSetAttrs instead of using the defaults 
mask. 
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PMERR_INV_MARKER_SET_ATTR 

PMERRINVMARKERSYMBOLATTR 

PMERR_INV_PATTERN_SET_ATTR 

PMERR_INV_PATTERN_ATTR 

PMERRINVCOORDINATE 


An invalid marker set attribute value was specified or the 
default value was explicitly specified with GpiSetAttrs 
instead of using the defaults mask. 

An invalid marker symbol attribute value was specified or 
the default value was explicitly specified with GpiSetAttrs 
instead of using the defaults mask. 

An invalid pattern set attribute value was specified or the 
default value was explicitly specified with GpiSetAttrs 
instead of using the defaults mask. 

An invalid pattern symbol attribute value was specified or 
the default value was explicitly specified with GpiSetAttrs 
instead of using the defaults mask. 

An invalid coordinate value was specified. 


PMERR_UNSUPPORTED_ATTR_VALUE An attribute value was specified with GpiSetAttrs that is 

not supported. 

PMERR_INV_PATTERN_SET_FONT An attempt was made to use an unsuitable font as a 

pattern set. 


PMERR_HUGE_FONTS_NOT SUPPORTED An attempt was made using GpiSetCharSet, 

GpiSetPatternSet, GpiSetMarkerSet, or GpiSetAttrs to 
select a font that is larger than the maximum size (64Kb) 
supported by the target device driver. 


Remarks 

Any attribute (for the specified primitive type) for which the appropriate flag is set in the flAttrMask 
has its value updated: 

• If the corresponding flag in fIDefMask is also set, the attribute is set to default. 

• If the corresponding flag in fIDefMask is not set, the attribute is set to the value specified in the 
ppbunAttrs structure. 

Any attribute for which the appropriate flag in flAttrMask is not set is unchanged, regardless of the 
setting of the corresponding flag in fIDefMask. 

The fIDefMask and flAttrMask parameters each contain flags: each attribute of the primitive type in 
question is represented by one flag. 

The data in the ppbunAttrs buffer consists of a structure of attribute data. The layout of the structure 
is fixed for each primitive type. Only data for attributes for which the flag is set in flAttrMask (but not 
in fIDefMask) is inspected; any other data is ignored. 

Note: The buffer need be no longer than is necessary to contain the data for the highest offset 
attribute referenced. 

If default values of attributes are required, they must be requested using the fIDefMask. The system 
does not recognize attribute values whose meaning would normally be “use default” in the 
ppbunAttrs buffer. 

Where possible, invalid color values are detected by this call and cause an error 
(PMERR_INV_COLO R_ATTR or PMERR_INV_BACKGROUND_COL_ATTR) to be logged. Some invalid 
color values cannot be detected until draw time at which point the implementation optionally defaults 
them, or causes the above error to be logged. If an attempt to set an invalid value by this function is 
detected, none of the specified attributes is changed. Note, however, that some invalid attribute 
values (for example, colors and mixes) may not be detected until the attribute is used. 
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If this function occurs within a path bracket, it must only set: 

• Line attributes, other than the geometric line width 

• Character attributes, other than foreground or background colors or mixes 

• Marker attributes, other than foreground or background colors or mixes. 

The default values of attributes can be changed with GpiSetDefAttrs. 

The attribute mode (see GpiSetAttrMode) determines whether the current values of the attributes are 
preserved. If they are, one “push” call is generated for each affected attribute, in the order in which 
the attributes are specified, in the appropriate xxxBUNDLE structure. 


Related Functions 

• GpiPop 

• GpiQueryAttrs 

• GpiSetAttrMode 

• GpiSetDefAttrs 

Graphic Elements and Orders 

The element type depends on the IPrimType parameter. 

For each element, the “Set” orders are generated, if the attribute mode (see GpiSetAttrMode) is set 
to AM_NOPRESERVE, and the “Push and Set” orders if it is AM_PRESERVE. In either instance, a 
particular order is generated only if the corresponding attribute is being set with this function, as 
specified on the ppbunAttrs parameter. 

Element Type: ETYPE_LINEBUNDLE 

Generated if IPrimType is PRIMJJNE. 

Order: Set Individual Attribute 

One of these for each of LBB_COLOR, and LBB_MIX_MODE, as required. 

Order: Set Fractional Line Width 

LBB_WIDTH, as required. 

Order: Set Stroke Line Width 

LBB_GEOM_WIDTH, as required. 

Order: Set Line Type 

LBB_TYPE, as required. 

Order: Set Line End 
LBB_END, as required. 

Order: Set Line Join 
LBB_JOIN, as required. 
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As many as required of the following are generated if the attribute mode is AM_PRESERVE: 
Order: Push and Set Individual Attribute 

One of these for each of LBB_COLOR, and LBB _MIX_MODE, as required. 

Order: Push and Set Fractional Line Width 

LBB_WIDTH, as required. 

Order: Push and Set Stroke Line Width 

LBB_GEOM_WIDTH, as required. 

Order: Push and Set Line Type 

LBB_TYPE, as required. 

Order: Push and Set Line End 

LBB_END, as required. 

Order: Push and Set Line Join 

LBB_JOIN, as required. 

Element Type: ETYPE_CHARBUNDLE 

Generated if IPrimType is PRIM_CHAR. 

Order: Set Individual Attribute 

One of these for each of CBB_COLOR, CBB_BACK_COLOR, CBB_MIX_MODE, and 
CBB_BACK_MIX_MODE, as required. 

Order: Set Character Set 

CBB_SET 

Order: Set Character Precision 

CBB_MODE 

Order: Set Character Cell 

CBB_BOX 

Order: Set Character Angle 

CBB_ANGLE 

Order: Set Character Shear 

CBB_SHEAR 

Order: Set Character Direction 
CBB_DIRECTION 

As many as required of the following are generated if the attribute mode is AM PRESERVE: 
Order: Push and Set Individual Attribute 

One of these for each of CBB_COLOR, CBB_BACK_COLOR, CBB_MIX_MODE, and 
CBB_BACK_MIX_MODE, as required. 

Order: Push and Set Character Set 

CBB_SET 

Order: Push and Set Character Precision 

CBB_MODE 

Order: Push and Set Character Cell 

CBB_BOX 

Order: Push and Set Character Angle 

CBB_ANGLE 

Order: Push and Set Character Shear 

CBB_SHEAR 

Order: Push and Set Character Direction 

CBB_DIRECTION 
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Element Type: ETYPE_MARKERBUNDLE 

Generated if IPrimType is PRIM_MARKER. 

Order: Set Individual Attribute 

One of these for each of MBB_COLOR, MBB_BACK_COLOR, MBB_MIX_MODE, and 
MBB_BACK_MIX_MODE, as required. 

Order: Set Marker Set 
MBB_SET 

Order: Set Marker Symbol 
MBB_SYMBOL 

Order: Set Marker Cell 
MBB_BOX 

As many as required of the following are generated if the attribute mode is AM_PRESERVE: 
Order: Push and Set Individual Attribute 

One of these for each of MBB_COLOR, MBB_BACK_COLOR, MBB_MIX_MODE, and 
MBB_BACK_MIX_MODE, as required. 

Order: Push and Set Marker Set 

MBB_SET 

Order: Push and Set Marker Symbol 

MBB_SYMBOL 

Order: Push and Set Marker Cell 
MBB_BOX 

Element Type: ETYPE_AREABUNDLE 

Generated if IPrimType is PRIM_AREA. 

Order: Set Individual Attribute 

One of these for each of ABB_COLOR, ABB_BACK_COLOR, ABB_MIX_MODE, and 
ABB_BACK_MIX_MODE, as required. 

Order: Set Pattern Set 

ABB_SET 

Order: Set Pattern Symbol 
ABB_SYMBOL 

Order: Set Pattern Reference Point 

ABB_REF_POINT 

As many as required of the following are generated if the attribute mode is AM_PRESERVE: 
Order: Push and Set Individual Attribute 

One of these for each of ABB_COLOR, ABB_BACK_COLOR, ABB_MIX_MODE, and 
ABB_BACK_MIX_MODE, as required. 

Order: Push and Set Pattern Set 

ABB_SET 

Order: Push and Set Pattern Symbol 

ABB_SYMBOL 

Order: Push and Set Pattern Reference Point 

ABB_REF_POINT 

Element Type: ETYPEJMAGEBUNDLE 

Generated if IPrimType is PRIMJMAGE. 

Order: Set Individual Attribute 

One of these for each of IBB_COLOR, IBB_BACK_COLOR, IBB_MIX_MODE, and 
IB B_BACK_M IX_MODE, as required. 
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As many as required of the following are generated if the attribute mode is AM_PRESERVE: 

Order: Push and Set Individual Attribute 

One of these for each of IBB_COLOR, IBB_BACK_COLOR, IBB_MIX_MODE, and 
IBB_BACK_MIX_MODE, as required. 

Example Code 

This example uses the GpiSetAttrs function to set the line color to red and the line width to its default 
value. 

Idefine INCL_GPIPRIMITIVES 
linclude <0S2.H> 

HPS hps; /* Presentation-space */ 

/* handle. */ 

LINEBUNDLE lbnd; 

Ibnd.lColor = CLR_RED; 

/* presentation-space handle */ 

/* 1 ine primitive. */ 

/* sets line color and width. */ 

/* sets line width to default */ 

/* buffer for attributes. */ 


GpiSetAttrs (hps, 

PRIM LINE, 

LBB_C0L0R | LBB_WIDTH, 
LBB WIDTH, 

&lbnd) ; 


Chapter 5. Graphics Functions 5-411 



GpiSetBackColor - 
Set Background Color 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetBackColor (HPS hps, LONG IColor) 


This function sets the current background color index attribute, for each individual primitive type, to 
the specified value. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

IColor (LONG) - input 
Background color: 


For a loadable color table, values 0 through n correspond to the color index (or RGB) values. 


CLR_FALSE 

CLR_TRUE 

CLRDEFAULT 


CLR_ WHITE 
CLRBLACK 


All color planes are zeros. 

All color planes are ones. 

Set to default value. This is the natural background color for the device. 
For a display, it is the default window color (SYSCLR_WINDOW: see 
WinSetSysColors). For a printer, it is the paper color. The default can be 
changed by setting new system colors from the control panel for the 
display, or by selecting a paper color for a printer (if allowed by the 
device driver), or set explicitly with GpiSetDefAttrs. 

White (default color table, or index=RGB loaded color table). For a 
loaded, realized, color table, it is the nearest available color to white. 

Black (default color table, or index=RGB loaded color table). For a 
loaded, realized, color table, it is the nearest available color to black. 


CLR_BACKGROUND Reset color, used by GpiErase. This is the natural background color for 
the device. For a display, it is the default window color 
(SYSCLR_WINDOW: see WinSetSysColors) for the default color table. For 
a printer, it is the paper color. For a loaded color table, it is color index 
0. For an RGB color table, it is color 000000 (black). 

CLR BLUE Blue (default color table). 


CLR_RED Red (default color table). 

CLR_PINK Pink (default color table). 


CLR_GREEN Green (default color table). 

CLR CYAN Cyan (default color table). 

CLR_YELLOW Yellow (default color table). 


CLR_NEUTRAL Neutral (default color table). A device-dependent color, that for the 

default color table provides a contrasting color to CLR_BACKGROUND. 
For a display, it is the default window text color (SYSCLR_WINDOWTEXT: 
see WinSetSysColors). For a printer, it is a color that contrasts with the 
paper color. For a loaded color table, it is color index 7; in RGB mode it 
is interpreted as color 000007. 


CLR_DARKGRAY Dark gray (default color table). 
CLR_DARKBLUE Dark blue (default color table). 
CLR_DARKRED Dark red (default color table). 
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CLRDARKPINK 

CLRDARKGREEN 

CLRDARKCYAN 

CLRBROWN 

CLRPALEGRAY 


Dark pink (default color table). 

Dark green (default color table). 

Dark cyan (default color table). 

Brown (default color table). 

Pale gray (default color table). 

For a loadable color table, values 0 through n correspond to the color 
index (or RGB) values. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 


PMERR_INV_HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 


PMERR_INV_BACKGROUND_COL_ATTR An invalid background color attribute value was specified 

or the default value was explicitly specified with 
GpiSetAttrs instead of using the defaults mask. 


Remarks 

Note that if the background mix is BM LEAVEALONE (the default setting), the background color is not 
seen. 

An attempt to set a negative color value, other than one for which a constant is defined, causes the 
error PMERR_INV_COLOR_ATTR to be logged. Other color values are allowed, although an error is 
generated when the color value is needed for drawing if it is invalid for the color table in use at that 
time (see GpiCreateLogColorTable). 

For details of how colors are handled on monochrome devices, also see GpiCreateLogColorTable. 

The attribute mode determines whether the current value of the background color attribute is 
preserved. If it is, the values of the background color attribute, for each primitive type, are 
preserved, and a single GpiPop function restores them. 

This function must not be used within a path or area bracket. 


Related Functions 

• GpiQueryBackColor 

• GpiSetBackMix 

• GpiSetColor 

• GpiSetMix 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiCharString 

• GpiCharStringAt 

• GpiCharStringPos 

• GpiCharStringPosAt 

• GpiQueryCharStringPos 

• GpiQueryCharStringPosAt 
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• GpiBox 

• GpiMarker 

• GpiPolyMarker 

• GpiFullArc 

• GpiPartialArc 

• GpiPointArc 

• GpiPolyFillet 

• GpiPolyFilletSharp 

• GpiPolySpline 

• GpiBeginArea 

• GpiEndArea 

Graphic Elements and Orders 

Element Type: OCODE_GSBICOL 

This element type is generated if the attribute mode (see GpiSetAttrMode) is set to 
AM_NOPRESERVE. 

Order: Set Background Indexed Color 
Element Type: OCODE_GPSBICOL 

This element type is generated if the attribute mode is set to AM_PRESERVE. 

Order: Push and Set Background Indexed Color 

Example Code 

This is an example of a function used to repaint the window when a WM_PAINT message is issued. 

Idefine INCL_GPIPRIMITIVES 
linclude <0S2.H> 

void ClientPaint( HWND hwnd ) 

{ 

POINTL pt; 

HPS hps; /* Presentation space handle */ 

RECTL rcl; /* Window rectangle */ 

long clrText; 

/* Obtain a cache PS and set color 
and background nix attributes */ 
hps = WinBeginPaint( hwnd, (HPS)NULLHANDLE, (PRECTL)&rcl ); 

GpiSetColor( hps, clrText ); 

GpiSetBackColor( hps, CLR_BACKGROUND ); /* set background 

to white. */ 

GpiSetBackMix( hps, BM_OVERPAINT ); 

} 
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#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM 7 


BOOL GpiSetBackMix (HPS hps, LONG IMixMode) 


This function sets the current background mix attribute for each individual primitive type. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

IMixMode (LONG) - input 
Background-mix mode. 

Background mixes marked with an asterisk (*) are mandatory for all devices. 

The currently associated device supports any of the mixes specified as supported in 
DevQueryCaps (CAPS_BACKGROUND_MIX_SUPPORT). Any other valid mixes can be supported 
for some primitive types but otherwise result in BMLEAVEALONE. An error is raised only if the 
value specified is not one of those listed. 

For more information on mixing, see GpiSetMix. 

BM DEFAULT The default value (BM LEAVEALONE unless changed with GpiSetDefAttrs). 

BMOR Logical-OR. 

BM OVERPAINT The background of the primitive takes precedence over whatever is 
underneath. (*) 

BMXOR Exclusive-OR. 

BM LEAVEALONE The background of the primitive has no effect on what is underneath. (*) 

Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRJNVHPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_BACKGROUND_COL_ATTR An invalid background color attribute value was specified 

or the default value was explicitly specified with 
GpiSetAttrs instead of using the defaults mask. 

Remarks 

The background mix attribute controls the way that the background color of a primitive is combined 
with the color of any primitive that it overlaps. 

These primitives are affected by the background mix attribute: 

Areas The background of an area is defined to be every pel within the area that is not set by the 
shading pattern. 

Text The background of a character is the complete character box. 

Images For an image, the background is every pel within the image that is not set. 
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Markers The background of a marker is the complete marker box. 

Note: When the background mix is BM_LEAVEALONE (initial default) the background color is not 
seen. 

The attribute mode determines whether the current value of the background mix attribute is 
preserved. If it is, the values of the background mix attribute for each primitive type are preserved, 
and a single GpiPop function restores them. 

This function should not be used within a path or area bracket. 

Note: There are restrictions on the use of this function when creating SAA-conforming metafiles; 
see “Metafile Restrictions” on page G-1. 

Related Functions 

• GpiQueryBackMix 

• GpiSetBackColor 

• GpiSetColor 

• GpiSetMix 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiCharString 

• GpiCharStringAt 

• GpiCharStringPos 

• GpiCharStringPosAt 

• GpiQueryCharStringPos 

• GpiQueryCharStringPosAt 

• GpiBox 

• GpiMarker 

• GpiPolyMarker 

• GpiFullArc 

• GpiBeginArea 

• GpiEndArea 

Graphic Elements and Orders 

Element Type: OCODE_GSBMX 

This element type is generated if the attribute mode (see GpiSetAttrMode) is set to 
AM_NOPRESERVE. 

Order: Set Background Mix 

Element Type: OCODE_GPSBMX 

This element type is generated if the attribute mode is set to AM_PRESERVE. 

Order: Push and Set Background Mix 
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GpiSetBackMix - 
Set Background Mix 


Example Code 

This is an example of a function used to repaint the window when a WM PAINT message is issued. 


VOID cdecl Cl i entPai nt ( HWND hwnd ) 

{ 

POINTL pt; 

HPS hps; /* Presentation space handle */ 

RECTL rcl; /* Window rectangle */ 


/* Obtain a cache PS and set color 
and background mix attributes */ 
hps = WinBeginPaint( hwnd, (HPS)NULLHANDLE, (PRECTL)&rcl ); 
GpiSetColor( hps, clrText ); 

GpiSetBackColor( hps, CLR_BACKGROUND ); /* set background 

to white. 

GpiSetBackMix( hps, BM_OVERPAINT ); 

/* the background of the primitive takes 
over whatever is underneath. 

} 


*/ 

*/ 
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GpiSetBitmap - 
Set Bit Map 


#define INCL_GPIBITMAPS /* Or use INCL_GPI or INCL_PM. Also in COMMON section */ 


HBITMAP GpiSetBitmap (HPS hps, HBITMAP hbm) 


This function sets a bit map as the currently selected bit map in a memory device context. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

hbm (HBITMAP) - input 

Handle of the bit map to be set. 

A null handle causes the currently selected bit map, in the associated device, to be freed. 
It is an error if the bit map is currently tagged for area shading (see GpiSetBitmapId). 


Returns 

Old bit-map handle: 

NULLHANDLE Correct (null handle) 

HBM_ERROR Error 
Otherwise Old bit-map handle. 

Possible returns from WinGetLastError 

An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid bit-map handle was specified. 

An attempt was made either to set a bitmap into a device 
context using GpiSetBitmap while it was already selected 
into an existing device context, or to tag a bit map with a 
local pattern set identifier (setid) using GpiSetBitmapId 
while it was already tagged with an existing setid. 

PMERR_INCOMPATIBLE_BITMAP An attempt was made to select a bit map or perform a 

BitBIt operation on a device context that was 
incompatible with the format of the bit map. 

PMERR_HBITMAP_BUSY An internal bit map busy error was detected. The bit map 

was locked by one thread during an attempt to access it 
from another thread. 


PMERR_INV_HPS 

PMERR_PS_BUSY 

PMERRINVHBITMAP 

PMERRBITMAPINUSE 


Remarks 

The specified presentation space must be currently associated with a memory device context. The 
device context can represent a different physical device from the one that the bit map originally 
loaded or created, providing its format is convertible to one supported on the new device. This is 
ensured when one of the standard formats is being used. 

If a bit map is already current in the device context, the handle of this bit map is returned, before the 
new bit map is selected. 

It is an error if the new bit map is already selected as the current bit map in any device context. 
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GpiSetBitmap - 
Set Bit Map 


Related Functions 

• GpiBitBIt 

• GpiCreateBitmap 

• GpiDeleteBitmap 

• GpiDrawBits 

• GpiLoadBitmap 

• GpiQueryBitmapBits 

• GpiQueryBitmapDimension 

• GpiQueryBitmapHandle 

• GpiQueryBitmapParameters 

• GpiQueryDeviceBitmapFormats 

• GpiSetBitmapBits 

• GpiSetBitmapDimension 

• GpiSetBitmapId 

• GpiWCBitBIt 

• WinDrawBitmap 

• WinGetSysBitmap 

Example Code 

This example uses the GpiSetBitmap function to set a newly created bit map in the device context for 
the associated presentation space. Once set, the example initializes the bit map image by drawing 
in the presentation space. 

Idefine INCL_GPIBITMAPS 
fdefine INCL_GPIPRIMITIVES 
linclude <0S2.H> 

HPS hps; /* Presentation space handle */ 

BITMAPINF0HEADER2 bmp = {12, 64, 64, 1, 1};/* 64x64 mono bit map */ 

HBITMAP hbm, hbmOld; 

POINTL ptl Start = { 0, 0 }; 

POINTL aptl Triangle [3] = { 32, 32, 63, 63, 0, 0 }; 

POINTL ptl = { 63, 63 }; 

hbm = GpiCreateBitmap (hps, 

&bmp, 

OL, 

NULL, 

NULL) ; 

/* Set the bit map and draw in it. */ 

/* sets bit map in device context */ 
hbmOld = GpiSetBitmap (hps, hbm); 

GpiMove(hps, &ptl Start); 

GpiBox(hps, DROFILL, &ptl, 0L, 0L); /* fills in the bit map */ 

GpiPolyLine(hps, /* draws a triangle */ 

1L, 

aptlTriangle) ; 

GpiSetBitmap(hps, hbmOld); /* restores the old bit map */ 
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GpiSetBitmapBits 
Set Bit-Map Bits 


#define INCL_GPIBITMAPS /* Or use INCL_GPI or INCL_PM 7 


LONG GpiSetBitmapBits (HPS hps, LONG IScanStart, LONG IScans, PBYTE pbBuffer, 
PBITMAPINF02 pbml2lnfoTable) 


This function transfers bit-map data from application storage to a bit map. 

Parameters 

bps (HPS) - input 

Presentation-space handle. 

IScanStart (LONG) - input 
Line number 

Scan-line number at which the data transfer is to start, counting from 0 as the bottom line. 

IScans (LONG) - input 

Number of scan lines to be transmitted. 

pbBuffer (PBYTE) - input 
Bit-map data buffer. 

Address in application storage from which the bit-map data is to be copied. 

pbml2lnfoTable (PBITMAPINF02) - input 
Bit-map information table. 


Returns 

Number of scan lines actually set: 

>0 Number of scan lines actually set 

GPI_ALTERROR Error. 


Possible returns from WinGetLastError 


PMERRINVHPS 

PMERR_PS_BUSY 

PMERR_INV_LENGTH_OR_COUNT 

PMERR_INV_INFO_TABLE 

PMERRNOBITMAPSELECTED 

PM E R R_IN V_SCAN_ST ART 

PMERR_INCORRECT_DC_TYPE 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid length or count parameter was specified. 

An invalid bit-map info table was specified with a bit-map 
operation. 

An attempt has been made to operate on a memory 
device context that has no bit map selected. 

An invalid scanstart parameter was specified with a 
bitmap function. 

An attempt was made to perform a bit-map operation on a 
presentation space associated with a device context of a 
type that is unable to support bit-map operations. 
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GpiSetBitmapBits - 
Set Bit-Map Bits 


Remarks 

The presentation space must be currently associated with a memory device context that has a bit 
map currently selected. 

Note: This function does not set bits directly to any other kind of device. 

If the format of the supplied bit map does not match that of the device, it is converted, using the 
supplied bit-map information table. The standard bit-map formats are supported, plus any known to 
be supported by the device; see GpiQueryDeviceBitmapFormats. 


Related Functions 

• GpiBitBIt 

• GpiCreateBitmap 

• GpiDeleteBitmap 

• GpiDrawBits 

• GpiLoadBitmap 

• GpiQueryBitmapBits 

• GpiQueryBitmapDimension 

• GpiQueryBitmapHandle 

• GpiQueryBitmapParameters 

• GpiQueryDeviceBitmapFormats 

• GpiSetBitmap 

• GpiSetBitmapDimension 

• GpiSetBitmapid 

• GpiWCBitBIt 

• WinDrawBitmap 

• WinGetSysBitmap 


Chapter 5. Graphics Functions 5-421 



GpiSetBitmapBits 
Set Bit-Map Bits 


Example Code 

This example uses the GpiSetBitmapBits function to copy image data to a bit map in a presentation 
space associated with a memory device context. 

Idefine INCL_GPI PRIMITIVES 
Idefine INCL_GPIBITMAPS 
Idefine INCL_DOSMEMMGR 
Idefine INCL.WINDIALOGS. 
linclude <0S2.H> 

HPS hps; /* Presentation space handle */ 

BITMAPINF0HEADER2 bmp = { 12, 32, 16, 1, 1 }; 

SEL sel ; 

PBITMAPINF0HEADER2 pbmi ; 

BYTE pbBuffer[16] ; /* buffer for image data */ 

ULONG cbBitmapInfo; 

HBITMAP hbm, hbmOld; 

BOOL f; 

/* Allocate space for the bit-map information table. */ 

cbBitmapInfo = sizeof(BITMAPINFO) + sizeof(RGB); 
f = (BOOL)DosAllocMem((PPVOID)pbmi, 

(ULONG)cbBitmapInfo, 

PAG_READ | 

PAG_WRITE | 

PAG_COMMIT)) ; 

if (f) { 

Wi nMessageBox ( HWN0_DESKT0P , HWND_DESKTOP, 

"Sorry, Not enough memory", 

NULL, 

0, 

MB_0K) ; 

return; 

} 

/* Initialize the bit-map information table. */ 

pbmi->cbFix = 12; 
pbmi->cx = 32; 
pbmi ->cy = 16; 
pbmi->cPlanes = 1; 
pbmi ->cBitCount = 1; 

/* Create the bit map, set to the device, 
and copy the image data. */ 

hbm = GpiCreateBitmap(hps, 
pbmi , 

0L, 

NULL, 

NULL); 

hbmOld = GpiSetBitmap(hps, hbm); 

Gpi SetBi tmapBi ts (hps , 

0L, 

(LONG) bmp. cy, 
pbBuffer, 
pbmi ) ; 

Gpi SetBi tmap (hps, hbmOld); 
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GpiSetBitmapDimension - 
Set Bit-Map Dimension 


#define INCL_GPIBITMAPS /* Or use INCL_GPI or INCL_PM 7 


BOOL GpiSetBitmapDimension (HBITMAP hbm, PSIZEL psizIBItmapDimension) 


This function associates a width and height with a bit map, in units of 0.1 millimeter. 


Parameters 

hbm (HBITMAP) - input 
Bit-map handle. 

psizIBItmapDimension (PSIZEL) - input 
Width and height of bit map. 

The width and height, respectively, of the bit map in units of 0.1 millimeter. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERR INV HBITMAP An invalid bit-map handle was specified. 

PMERR_HBITMAP_BUSY An internal bit map busy error was detected. The bit map 

was locked by one thread during an attempt to access it 
from another thread. 


Remarks 

The values set are not used internally by the system, but are retained with the bit map and can be 
retrieved with GpiQueryBitmapDimension. 


Related Functions 

• GpiBitBIt 

• GpiCreateBitmap 

• GpiDeleteBitmap 

• GpiDrawBits 

• GpiLoadBitmap 

• GpiQueryBitmapBits 

• GpiQueryBitmapDimension 

• GpiQueryBitmapHandle 

• GpiQueryBitmapParameters 

• GpiQueryDeviceBitmapFormats 

• GpiSetBitmap 

• GpiSetBitmapBits 

• GpiSetBitmapid 

• GpiWCBitBIt 

• WinDrawBitmap 

• WinGetSysBitmap 
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GpiSetBitmapDimension 
Set Bit-Map Dimension 


Example Code 

This example uses the GpiSetBitmap and GpiSetBitmapDimension function to set a newly created bit 
map in the device context for the associated presentation space. Once set, the example initializes 
the bit-map image by drawing in the presentation space. 

Idefine INCL_GPIBITMAPS 
fdefine I NCL_GPI PRIMITIVES 
linclude <0S2.H> 

HPS hps; /* Presentation space handle */ 

BOOL f Success; /* Success indicator */ 

BITMAPINF0HEADER2 bmp = {12, 64, 64, 1, 1};/* 64x64 mono bit map */ 

HBITMAP hbm, hbmOld; 

POINTL ptl Start = { 0, 0 }; 

POINTL aptl Triangle [3] = { 32, 32, 63, 63, 0, 0 }; 

POINTL ptl = { 63, 63 }; 

SIZEL sizlBitmapDimension = {100, 100}; 

/* The width and height, */ 

/* respectively, of the bit */ 

/* map in units of 0.1 */ 

/* millimeter. */ 

hbm = GpiCreateBitmap(hps, 

&bmp, 

0L, 

NULL, 

NULL); 

/* Set the bit map and draw in it. */ 

fSuccess = GpiSetBitmapDimension(hbm, 

&s i z 1 Bi tmapDi mens ion); 
hbmOld = GpiSetBitmap(hps, hbm); /* sets bit map 

in device context */ 

GpiMove(hps, &ptl Start); 

GpiBox(hps, DR0_FILL, &ptl , 0L, 0L) ; /* fills in the bit map */ 

GpiPolyLine(hps, /* draws a triangle */ 

1L, 

aptlTri angle) ; 

GpiSetBitmap(hps, hbmOld); /* restores the old bit map*/ 
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GpiSetBitmapId - 
Set Bit-Map Identifier 


#define INCL_GPIBITMAPS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetBitmapId (HPS hps, HBITMAP hbm, LONG ILcid) 


This function tags a bit map with a local identifier, so that it can be used as a pattern set, containing a 
single member. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

hbm (HBITMAP) - input 
Bit-map handle. 

The bit map must not be currently selected into a device context (see GpiSetBitmap). 

ILcid (LONG) - input 

Local identifier with which the bit map is to be tagged. 

Valid values are in the range 1 through 254. 

It is an error if the local identifier is already used to refer to a font or bit map. 

Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRINVHPS 
PMERRPSBUSY 

PMERRINVHBITMAP 
PMERRJNVSETID 
PMERRSETIDINUSE 

PMERRBITMAPJNUSE 


PMERRHBITMAPBUSY 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid bit-map handle was specified. 

An invalid setid parameter was specified. 

An attempt was made to specify a setid that was already 
in use as the currently selected character, marker or 
pattern set. 

An attempt was made either to set a bit map into a device 
context using GpiSetBitmap while it was already selected 
into an existing device context, or to tag a bit map with a 
local pattern set identifier (setid) using GpiSetBitmapId 
while it was already tagged with an existing setid. 

An internal bitmap busy error was detected. The bit map 
was locked by one thread during an attempt to access it 
from another thread. 
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GpiSetBitmapId - 
Set Bit-Map Identifier 


Remarks 

To use the bit map for area shading (or as the pattern in a GpiBitBIt or GpiWCBitBIt operation), a 
GpiSetPatternSet must be issued with the specified local identifier. 

Any bit map of a format supported by the device can be specified. However, it may be simplified 
before use (see GpiSetPatternSet). 

GpiDeleteSetld can subsequently be used to release the tag. 


Related Functions 

• GpiBitBIt 

• GpiCreateBitmap 

• GpiDeleteBitmap 

• GpiDrawBits 

• GpiLoadBitmap 

• GpiQueryBitmapBits 

• GpiQueryBitmapDimension 

• GpiQueryBitmapHandle 

• GpiQueryBitmapParameters 

• GpiQueryDeviceBitmapFormats 

• GpiSetBitmap 

• GpiSetBitmapBits 

• GpiSetBitmapDimension 

• GpiWCBitBIt 

• WinDrawBitmap 

• WinGetSysBitmap 

• GpiDeleteSetld 

• GpiSetPatternSet 

Example Code 

This function tags a bit map with a local identifier, so that it can be used as a pattern set, containing a 
single member. 

Idefine INCL_GPIBITMAPS 
linclude <0S2.H> 

HPS hps; /* Presentation space handle */ 

HBITMAP hbm; /* bit-map handle. */ 

LONG lid = 23; /* local identifier. */ 

GpiSetBitmapId(hps, 

hbm, 

lid); 
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GpiSetCharAngle - 
Set Character Angle 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetCharAngle (HPS hps, PGRADIENTL pgradlAngle) 


This function specifies the angle of the baseline for the characters in a string, as a relative vector. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

pgradlAngle (PGRADIENTL) - input 
Baseline angle. 

The baseline angle is defined in terms of the relative coordinates of the point pgradlAngle (x, y). 

If both x and y are 0, the character angle is reset to the default value. This default value is (1,0), 
unless changed with GpiSetDefAttrs. 

Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERR_INV_HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

Remarks 

The coordinates of the point pgradlAngle specify integer values for the coordinates of the end of a 
line starting at the origin (0,0); the base line for subsequent character strings is parallel to this line. 

The effect of the baseline angle attribute depends on the value of the character mode attribute (see 
GpiSetCharMode), and whether the current font is an outline or a raster font, as described below. 

When the character mode is set to CM_MODE1 , and the current font is a raster font, the character 
angle can be ignored. 

When the character mode is set to CM_MODE2, and the current font is a raster font, the angle is used 
to determine the position of each character, but the orientations of characters within the character 
box may not be affected by changes in character angle. If this is so, the characters are positioned so 
that the lower left-hand corners of the character definitions are placed at the lower lefMiand corners 
of the character boxes after all transforms have been applied. This is illustrated in Figure 5-7 on 
page 5-428. 
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GpiSetCharAngle - 
Set Character Angle 


For illustrative purposes, the figure shows all character reference points at their bottom left-hand 
corner. 


ax = 2 
ay = 1 



When the character mode is set to CM_MODE3, or when the current font is an outline font, the angle 
is observed accurately, and the character boxes are rotated to be normal (perpendicular) to the 
character baseline. If the world coordinate system is such that one x-axis unit is not physically equal 
to one y-axis unit, a rotated character string appears to be sheared. 

This function must not be issued in an area bracket. 

The attribute mode determines whether the current value of the baseline angle attribute is 
preserved. 


Related Functions 

• GpiQueryCharAngle 

• GpiSetCharBox 

• GpiSetCharDirection 

• GpiSetCharMode 

• GpiSetCharSet 

• GpiSetCharShear 

• GpiPop 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiSetBackColor 

• GpiSetBackMix 

• GpiSetColor 

• GpiSetMix 

• GpiCharString 

• GpiCharStringAt 

• GpiCharStringPos 

• GpiCharStringPosAt 

• GpiQueryCharStringPos 

• GpiQueryCharStringPosAt 
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GpiSetCharAngle - 
Set Character Angle 


Graphic Elements and Orders 

Element Type: OCODE_GSCA 

This element type is generated if the attribute mode (see GpiSetAttrMode) is set to 
AM_NOPRESERVE. 

Order: Set Character Angle 

Element Type: OCODE_GPSCA 

This element type is generated if the attribute mode is set to AM_PRESERVE. 

Order: Push and Set Character Angle 

Example Code 

This function resets the angle of the baseline for the characters in a string, as a relative vector. 

Idefine INCL_GPIPRIMITIVES 
linclude <0S2.H> 

HPS hps; 

GRADIENTL gradlAngle = {0L, 0L}; 

Gpi SetCharAngl e ( hps , 

&gradl Angle) ; 
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GpiSetCharBox - 
Set Character Box 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM 7 


BOOL GpiSetCharBox (HPS hps, PSIZEF psIzfxBox) 


This function sets the current character-box attribute to the specified value. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

psIzfxBox (PSIZEF) - input 

Character-box size in world coordinates. 

The width determines the spacing of consecutive characters along the baseline. 

Both width and height can be positive, negative, or zero. 

When either parameter is negative, the spacing occurs in the opposite direction to normal and 
each character is drawn reflected in character-mode 3. Thus, for example, a negative height in 
the standard direction in mode 3 means that the characters are drawn upside down, and the 
string drawn below the baseline (assuming no other transformations cause inversion). 

A zero character width or height is also valid; here, the string of characters becomes a line. If 
both are zero, the string is drawn as a single point. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERR INV HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

Remarks 

The parameter psizfxBox specifies values for the width and height of a character box in world 
coordinates. 

Whether these values are used when character strings are drawn depends on the type of font being 
used (raster or outline), and on the value of the character mode attribute (see the GpiSetCharMode 
function). 

For raster fonts, where the character box is used only for positioning in character mode CM_MODE2, 
the character box width corresponds to the lEmlnc font metric (see FONTMETRICS). For 
proportionally-spaced raster fonts, the effective spacing for a given character is the character box 
width, scaled by the ratio of that character’s width to lEmlnc. 

For outline fonts, characters are defined in font definition space. The sXDeviceRes and sYDeviceRes 
fields (see FONTMETRICS) define a rectangle in font definition space that is mapped to the character 
box rectangle (modified by the character angle and shear attributes) in world coordinates. 
sYDeviceRes corresponds to the font point size in font definition space, and therefore the character 
box height corresponds to the font point size in world coordinates. This is typically less than the 
IMaxBaselineExt. 
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GpiSetCharBox - 
Set Character Box 


The effective width of each character from an outline font is the character box width, scaled by the 
ratio of the width of the character to sXDeviceRes. The lAveCharWidth (for a proportionally-spaced 
font) will therefore typically be smaller than the character box width. Indeed, because of differences 
in font design, lAveCharWidth and IMaxBaselineExt vary between different fonts, even when the 
character box dimensions are the same. 

lEmlnc and lEmHeight are always equal to the character box width and height, respectively. 

To cause characters of a given point-size to be generated using an outline font, establish a world 
coordinate space with specific metrics (for example, specify PU_TWIPS on GpiCreatePS), and set the 
character box height to the required point size. Because sXDeviceRes and sYDeviceRes are 
normally equal, the character box width should also be set equal to the height, if characters are 
required with the same aspect ratio as defined in the font (assuming that world coordinate space is 
isotropic). 

The initial default value of the character box is the device-coordinates value returned by 
DevQueryCaps (CAPS_GRAPHICS_CHAR_WIDTH and CAPS_GRAPHICS_CHAR_HEIGHT), for the 
currently associated device, converted to page coordinates. 

Note: In general the initial default value is rectangular, and to avoid character distortion, the 

character box should normally be set explicitly to be square if an outline font might be used 
(assuming that world coordinate space is isotropic). 

The default value can be changed with GpiSetDefAttrs. 

GpiSetCharBox must not be issued in an area bracket. 

The attribute mode (see GpiSetAttrMode) determines whether the current value of the character-box 
size attribute is preserved. 


Related Functions 

• GpiQueryCharBox 

• GpiSetCharAngle 

• GpiSetCharDirection 

• GpiSetCharMode 

• GpiSetCharSet 

• GpiSetCharShear 

• GpiPop 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiSetBackColor 

• GpiSetBackMix 

• GpiSetColor 

• GpiSetMix 

• GpiCharString 

• GpiCharStringAt 

• GpiCharStringPos 

• GpiCharStringPosAt 

• GpiQueryCharStringPos 

• GpiQueryCharStringPosAt 
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GpiSetCharBox - 
Set Character Box 

Graphic Elements and Orders 

Element Type: OCODE_GSCC 

This element type is generated if the attribute mode (see GpiSetAttrMode) is set to 
AM NOPRESERVE. Note that GpiCreateLogFont can also generate this element type. 

Order: Set Character Cell 

Element Type: OCODE_GPSCC 

This element type is generated if the attribute mode is set to AM_PRESERVE. 

Order: Push and Set Character Cell 


Example Code 

This function sets the current character-box attribute to the specified value. 

Idefine INCL_GPI PRIMITIVES 
linclude <0S2.H> 


HPS hps; /* Presentation space handle */ 

SIZEF sizfCharBox; /* Character-box size in */ 

/* world coordinates. */ 

sizfCharBox.cx = 8L«16; /* values are shifted to the */ 

sizfCharBox.cy = 20L«16; /* to make them fixed. */ 

GpiSetCharBox ( hps, 

&sizfCharBox ); 
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GpiSetCharBreakExtra - 
Set Character Break Extra 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetCharBreakExtra (HPS hps, FIXED fxBreakExtra) 


This function specifies an extra increment to be used for spacing break characters in a string. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

fxBreakExtra (FIXED) - input 
Character-break-extra value. 

The value can be negative, 0, or positive: 

• A negative value reduces the effective width of break characters. 

• A value of 0 results in normal spacing. 

• A positive value increases the effective width of break characters. 

The value is in world coordinates. 

Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERR_INV_HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 


Remarks 

The character-break-extra attribute provides a spacing value that increases or decreases the 
spacing for break characters in a string. The break character is defined by the font, and can be found 
by calling GpiQueryFonts (sBreakChar field in the FONTMETRICS structure). 

The break-extra spacing is additional to the spacing generated for other reasons, for example: 

• The spacing determined by the font, including proportional spacing and kerning, if applicable 

• The vector of increment values, see GpiCharStringPos, GpiCharStringPosAt, 
GpiQueryCharStringPos and GpiQueryCharStringPosAt 

• Extra spacing, see GpiSetCharExtra. 

Break-extra spacing applies to character strings either within or outside a path definition (see 
GpiBeginPath). The effect of the character-break-extra attribute applies whatever the value of the 
character-mode attribute (see GpiSetCharMode), and for both outline and raster fonts. 

This function must not be issued in an area bracket. 

The initial default value of the character-break-extra attribute is 0, which gives normal spacing. This 
default value can be changed with GpiSetDefAttrs. 
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GpiSetCharBreakExtra - 
Set Character Break Extra 


The attribute mode (see GpiSetAttrMode) determines whether the current value of the 
character-break-extra attribute is preserved. 

Graphic Elements and Orders 

Element Type: OCODE_GSCBE 

This element type is generated if the attribute mode (see GpiSetAttrMode) is set to 
AM_NOPRESERVE. 

Order: Set Character Break Extra 

Element Type: OCODE_GPSCBE 

This element type is generated if the attribute mode is set to AM_PRESERVE. 

Order: Push and Set Character Break Extra 

Example Code 

This function specifies an extra increment to be used for spacing break characters in a string. 

Idefine INCL_GPI PRIMITIVES 
linclude <0S2.H> 


HPS hps; /* Presentation space handle */ 

FIXED fxBreak; /* Character-break-extra value. */ 

/* world coordinates. */ 

fxBreak = 8L«16; /* values are shifted to the */ 

/* to make them fixed. */ 


Gpi SetCharBreakExtra ( hps , 

fxBreak) ; 
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GpiSetCharDirection - 
Set Character Direction 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetCharDirection (HPS hps, LONG IDirection) 


This function determines the direction in which the characters in a string are drawn relative to the 

baseline. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

IDirection (LONG) - input 

Character direction: 

CHDIRNDEFAULT The default; the same as CHDIRN_LEFTRIGHT (unless changed with 
GpiSetDefAttrs) 

CHDIRN LEFTRIGHT Character boxes are arranged parallel to, and in the same direction as, 
the baseline. This is the usual convention for Roman text. 

CHDIRN_TOPBOTTOM Character boxes are arranged in columns directed 90 degrees clockwise 
from the baseline. This is the usual convention for Chinese characters. 
This option can be used for drawing Roman text vertically (a y-axis title 
on a graph, for example). The reference point within the character 
definition is at the center of the character, along the x-direction, in this 
case. 

CHDIRN_RIGHTLEFT Character boxes are arranged parallel to, but in the reverse of, the 
baseline direction. This is the usual convention for Arabic text. 

CHDIRN BOTTOMTOP Character boxes are arranged in columns directed 90 degrees 

counterclockwise from the baseline. The reference point within the 
character definition is at the center of the character, along the 
x-direction, in this case. 

Returns 

Success indicator: 

TRUE Successful completion 

FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRINVHPS 

PMERRPSBUSY 

PMERR_INV_CHAR_DIRECTION_ATTR 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid character direction attribute value was 
specified or the default value was explicitly specified with 
GpiSetAttrs instead of using the defaults mask. 


Chapter 5. Graphics Functions 5-435 







GpiSetCharDirection - 
Set Character Direction 


Remarks 

This function must not be issued in an area bracket. The attribute mode determines whether the 
current value of the character direction attribute is preserved. This diagram shows how the origin of 
characters changes when the direction changes: 
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Figure 5-8. Character Drawing Directions and Character Box Origins 


Related Functions 

• GpiQueryCharDirection 

• GpiSetCharAngle 

• GpiSetCharBox 

• GpiSetCharMode 

• GpiSetCharSet 

• GpiSetCharShear 

• GpiPop 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiCharString 

• GpiCharStringAt 

• GpiCharStringPos 

• GpiCharStringPosAt 

• GpiQueryCharStringPos 

• GpiQueryCharStringPosAt 

Graphic Elements and Orders 

Element Type: OCODE GSCD 

This element type is generated if the attribute mode (see GpiSetAttrMode) is set to 
AM_NOPRESERVE. 

Order: Set Character Direction 
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GpiSetCharDirection - 
Set Character Direction 


Element Type: OCODE_GPSCD 

This element type is generated if the attribute mode is set to AM_PRESERVE. 

Order: Push and Set Character Direction 

Example Code 

This function determines the direction in which the characters in a string are drawn relative to the 
baseline. In this example, the direction is reset to the default, or left-to-right. 

Idefine INCL_GPIPRIMITIVES 
linclude <0S2.H> 


HPS hps; /* Presentation space handle */ 

Gpi SetCharDi rect i on ( hps , 

CHDIRN_DEFAULT) ; 
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Set Character Extra 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetCharExtra (HPS hps, FIXED fxExtra) 


This function specifies an extra increment to be used for spacing characters in a string. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

fxExtra (FIXED) - input 
Character-extra value. 

The value can be negative, 0, or positive: 

• A negative value forces the characters closer together. 

• A value of 0 results in normal spacing. 

• A positive value forces the characters further apart. 

The value is in world coordinates. 

Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERR INV HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

Remarks 

The character-extra attribute provides a spacing value that increases or decreases the spacing 
between characters in a string. It applies to all characters in a font, including the break character and 
is additional to the spacing generated for other reasons, for example: 

• The spacing determined by the font, including proportional spacing and kerning, if applicable 

• The vector of increment values, see GpiCharStringPos, GpiCharStringPosAt, 
GpiQueryCharStringPos and GpiQueryCharStringPosAt 

• Break-extra spacing, see GpiSetCharBreakExtra. 

Extra spacing applies to character strings either within or outside a path definition (see 
GpiBeginPath). The effect of the character-extra attribute applies whatever the value of the 
character-mode attribute (see GpiSetCharMode), and for both outline and raster fonts. 

This function must not be issued in an area bracket. 

The initial default value of the character-extra attribute is 0, which gives normal spacing. This default 
value can be changed with GpiSetDefAttrs. 

The attribute mode (see GpiSetAttrMode) determines whether the current value of the 
character-extra attribute is preserved. 
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GpiSetCharExtra - 
Set Character Extra 


Graphic Elements and Orders 

Element Type: OCODE_GSCE 

This element type Is generated if the attribute mode (see GpISetAttrMode) is set to 
AM_NOPRESERVE. 

Order: Set Character Extra 

Element Type: OCODE_GPSCE 

This element type is generated if the attribute mode is set to AM_PRESERVE. 

Order: Push and Set Character Extra 

Example Code 

This function specifies an extra increment to be used for spacing characters in a string. 

Idefine INCL_GPIPRIMITIVES 
linclude <0S2.H> 


HPS hps; /* Presentation space handle */ 
FIXED fxExtra; /* extra character. 

fxExtra = MAKEFIXED(0,0) /* normal spacing. */ 
Gpi SetCharExtra ( hps , fxExtra) ; 
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GpiSetCharMode - 
Set Character Mode 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetCharMode (HPS hps, LONG IMode) 


This function controls the character mode used when drawing a character string. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

IMode (LONG) - input 
Character mode: 

CM_DEFAULT The default; the same as CM MODE1 (unless changed with GpiSetDefAttrs). 

CM MODE1 The font selected by means of GpiSetCharSet can be either a raster font or an 
outline font. 


If it is a raster font, the position of characters after the first character is 
determined by the font metrics information, and by the character direction, 
character extra, and character break extra attributes. If it is an outline font, the 
behavior is as if the character mode is CMMODE3. 

CM MODE2 The font selected by means of GpiSetCharSet can be either a raster font or an 
outline font. 


If it is a raster font, the position of characters after the first character is 
determined by the font metrics information, and some character attributes, 
namely, GpiSetCharAngle, GpiSetCharBox, GpiSetCharDirection, 
GpiSetCharExtra, GpiSetCharBreakExtra, and GpiSetCharShear (the latter is 
relevant only for character directions of CHDIRN_TOPBOTTOM and 
CHDIRN_BOTTOMTOP). If it is an outline font, the behavior is as if the 
character mode is CM_MODE3. 

CM MODE3 All character attributes are used for positioning (together with the positioning 
information in the font), and for scaling, rotating, and shearing the characters. 

The font selected by means of GpiSetCharSet must be an outline font; an error 
is raised if an attempt is made to draw a character string in CM_MODE3, and 
the selected font is a raster font. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 

PMERR INV HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERRJNV_CHAR_MODE_ATTR An invalid character mode attribute value was specified 

or the default value was explicitly specified with 
GpiSetAttrs instead of using the defaults mask. 
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GpiSetCharMode - 
Set Character Mode 


Remarks 

The value of the IMode parameter controls whether the character attributes affect the positioning of 
characters, as follows: 


Table 5-1. Use of Character Attributes in each Character Mode 

Character 

Mode 

Font Type 

Character Attributes (Angle, Shear, and Box) 

Mode 1 

Raster 

Ignored 

Outline 

Used 

Mode 2 

Raster 

Attribute information is used to position characters: characters are not sheared, 
rotated, or scaled. 

Outline 

Used 

Mode 3 

Raster 

An error is raised when an attempt is made to draw a character string. 

Outline 

Used 


This function must not be issued in an area bracket. 

The attribute mode (see GpiSetAttrMode) determines whether the current value of the 
character-mode attribute is preserved. 


Related Functions 

• GpiQueryCharMode 

• GpiSetCharAngle 

• GpiSetCharBox 

• GpiSetCharDirection 

• GpiSetCharSet 

• GpiSetCharShear 

• GpiPop 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiCharString 

• GpiCharStringAt 

• GpiCharStringPos 

• GpiCharStringPosAt 

• GpiQueryCharStringPos 

• GpiQueryCharStringPosAt 

Graphic Elements and Orders 

Element Type: OCODE_GSCR 

This element type is generated if the attribute mode (see GpiSetAttrMode) is set to 
AM_NOPRESERVE. 

Order: Set Character Precision 

Element Type: OCODE_GPSCR 

This element type is generated if the attribute mode is set to AM_PRESERVE. 
Order: Push and Set Character Precision 
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GpiSetCharMode - 
Set Character Mode 


Example Code 

In this example the GpiSetCharMode call is used to set the character mode to raster or outline when 
drawing a string. 

Idefine INCL_GPIPRIMITIVES 
linclude <0S2.H> 


HPS hps; /* Presentation space handle */ 

Gpi SetCharMode(hps, 

CM_M0DE3); /* The font selected by */ 

/* means of */ 

/* GpiSetCharSet can be */ 

/* either a raster font or */ 
/* an outline font. */ 
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GpiSetCharSet - 
Set Character Set 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetCharSet (HPS hps, LONG Held) 


This function sets the current value of the character-set attribute. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

Held (LONG) - input 

Character-set local identifier: 

LCID DEFAULT Default (can be set explicitly with GpiSetDefAttrs). 
1-254 Identifies a logical font. 

Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRINVHPS 
PMERRPSBUSY 

PMERR_INV_CHAR_SET_ATTR 

PMERR_HUGE_FONTS_NOT_SUPPORTED 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid character setid attribute value was specified or 
the default value was explicitly specified with GpiSetAttrs 
instead of using the defaults mask. 

An attempt was made using GpiSetCharSet, 
GpiSetPatternSet, GpiSetMarkerSet, or GpiSetAttrs to 
select a font that is larger than the maximum size (64Kb) 
supported by the target device driver. 


Remarks 

This function must not be issued in an area bracket. 

The attribute mode (see GpiSetAttrMode) determines whether the current value of the character-set 
attribute is preserved. 
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GpiSetCharSet - 
Set Character Set 


Related Functions 

• GpiCreateLogFont 

• GpiQueryCharSet 

• GpiSetCharAngle 

• GpiSetCharBox 

• GpiSetCharDirection 

• GpiSetCharMode 

• GpiSetCharShear 

• GpiPop 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiCharString 

• GpiCharStringAt 

• GpiCharStringPos 

• GpiCharStringPosAt 

• GpiQueryCharStringPos 

• GpiQueryCharStringPosAt 

Graphic Elements and Orders 

Element Type: OCODE_GSCS 

This element type is generated if the attribute mode (see GpiSetAttrMode) is set to 
AM_NOPRESERVE. 

Order: Set Character Set 

Element Type: OCODE_GPSCS 

This element type is generated if the attribute mode is set to AMPRESERVE. 
Order: Push and Set Character Set 

Example Code 

This function sets the current value of the character-set attribute. 

Idefine INCL_GPIPRIMITIVES 
linclude <0S2.H> 


HPS hps; /* Presentation space handle */ 
LONG llcid = 32L; 

GpiSetCharSet (hps, llcid); 
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GpiSetCharShear - 
Set Character Shear 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetCharShear (HPS hps, PPOINTL pptlAngle) 


This function sets the character-shear attribute. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

pptlAngle (PPOINTL) - input 
Character shear vector. 

With reference to Figure 5-9 on page 5-446, the shear angle is defined in terms of the relative 
coordinates of the point pptlAngle (x, y). 

If x is 0 and y is 1 (initial default), “upright” characters result. If x and y are both positive or both 
negative, the characters slope from bottom-left to top-right. If x and y are of opposite signs, the 
characters slope from top-left to bottom-right. No character inversion ever takes place as a 
result of a shear alone. 

Usually, it is an error to specify 0 for y, because this implies an “infinite” shear. However, if 
both x and y are 0 , the attribute is set to the default value. This can be changed from the initial 
default with GpiSetDefAttrs. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERR_INV_HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_CHAR_SHEAR_ATTR An invalid character shear attribute value was specified 

or the default value was explicitly specified with 
GpiSetAttrs instead of using the defaults mask. 

PMERR_INV_COORDINATE An invalid coordinate value was specified. 

Remarks 

The coordinates of the point pptlAngle (x, y), specify integer values that identify the end coordinates 
of a line originating at (0,0) (see Figure 5-9 on page 5-446). The vertical strokes in subsequent 
character strings are drawn parallel to the defined line. The top of the character box remains 
parallel to the character baseline (which may itself be rotated). 

Whether this attribute is used when character strings are drawn depends on the type of font being 
used (raster or outline), and on the value of the character mode attribute (see GpiSetCharMode). If it 
is used, then with character directions of CHDIRN_TOPBOTTOM and CHDIRN_BOTTOMTOP (see 
GpiSetCharOirection) the whole string is tilted by the shear angle, in addition to the individual 
characters being sheared if the current font is an outline font. 

This function must not be issued in an area bracket. 


Chapter 5. Graphics Functions 5-445 






GpiSetCharShear - 
Set Character Shear 


The attribute mode (see GpiSetAttrMode) determines whether the current value of the character 
shear attribute is preserved. 



Figure 5-9. Character Shear 


Related Functions 

• GpiQueryCharShear 

• GpiSetGharAngle 

• GpiSetCharBox 

• GpiSetCharDirection 

• GpiSetCharMode 

• GpiSetCharSet 

• GpiPop 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiCharString 

• GpiCharStringAt 

• GpiCharStringPos 

• GpiCharStringPosAt 

• GpiQueryCharStringPos 

• GpiQueryCharStringPosAt 

Graphic Elements and Orders 

Element Type: OCODE_GSCH 

This element type is generated if the attribute mode (see GpiSetAttrMode) is set to 
AM_NOPRESERVE. 

Order: Set Character Shear 

Element Type: OCODE_GPSCH 

This element type is generated if the attribute mode is set to AM PRESERVE. 
Order: Push and Set Character Shear 
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GpiSetCharShear - 
Set Character Shear 


Example Code 

This function sets the character-shear attribute. 

Idefine INCL_GPIPRIMITIVES 
linclude <0S2.H> 


HPS hps; /* Presentation space handle */ 

POINTL ptlAngle = {50L, 70L}; /* character shear vector. */ 


Gpi SetCharShear ( hps , 

&ptlAngle); /* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


the shear */ 
angle is defined in terms */ 
of the relative */ 
coordinates of the point */ 
pptl Angle. This can be */ 
changed from the initial */ 
default with */ 
GpiSetDefAttrs. */ 
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GpiSetClipPath 
Set Clip Path 


#define INCL_GPIPATHS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetClipPath (HPS hps, LONG IPath, LONG lOptions) 


This function selects a path as the current clip path. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

IPath (LONG) - input 
Path control flag. 

0 The current clip path stops being the current clip path; the current clip path is to be reset to 
an infinite one (that is, no clipping). 

1 The path that has been defined is to be intersected with the current clip path. 

lOptions (LONG) - input 
Options. 

This contains fields of option bits. For each field, one value should be selected (unless the 
default is suitable). These values can then be ORed together to generate the parameter. 

How to construct the path interior (see also GpiBeginArea): 

SCPALTERNATE Construct interior in alternate mode. 

SCP_WINDING Construct interior in winding mode. This value must be selected if the path 
has been modified using GpiModifyPath. 

The default is SCP_ALTERNATE. 

Returns 

Success indicator; 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 


PMERRJNVHPS 

PMERRPSBUSY 

P M E R R_IN V_P ATH _ID 
PMERR_INV_CLIP_PATH_OPTIONS 

PMERRPATHUNKNOWN 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid path identifier parameter was specified. 

An invalid options parameter was specified with 
GpiSetClipPath. 

An attempt was made to perform a path function on a path 
that did not exist. 
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GpiSetClipPath - 
Set Clip Path 


Remarks 

The clip path (bound in device coordinates when the path is defined) is used for all subsequent 
drawing. 

Any open figures within the path are closed automatically. 

The boundaries of the area defined by the path are considered to be part of the interior, so that a 
point on the boundary is not clipped. 

The clip path is reset to no clipping (no path selected) at the start of a root segment (subject to the 
fast chaining segment attribute), or when a GpiResetPS function is issued. 

After a path is selected as the clip path, it cannot be reused for any other purpose. When it is 
superseded as the clip path, it is discarded. 


Related Functions 

• GpiBeginPath 

• GpiEndPath 

• GpiFillPath 

• GpiModifyPath 

• GpiOutlinePath 

• GpiPathToRegion 

• GpiStrokePath 

• GpiExcludeClipRectangle 

• GpilntersectClipRectangle 

• GpiOffsetClipRegion 

• GpiQueryClipBox 

• GpiQueryClipRegion 

• GpiSetClipPath 

• GpiSetClipRegion 

Graphic Elements and Orders 

Element Type: OCODE_GSCPTH 
Order: Select Clip Path 
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GpiSetClipPath 
Set Clip Path 


Example Code 

This function selects a path as the current clip path. 

Idefine INCL_GPIPATHS 
linclude <0S2.H> 


HPS hps; /* Presentation space handle */ 


Gpi SetCl i pPath(hps , 

OL, /* The current clip path */ 
/* stops being the */ 

/* current clip path; the */ 
/* current clip path is to */ 
/* be reset to an infinite */ 
/* one (that is, no */ 

/* clipping) */ 

SCP_ALTERNATE) ; 

/* Construct interior in */ 
/* alternate mode. */ 
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GpiSetClipRegion - 
Set Clip Region 


#define INCL_GPIREGIONS /* Or use INCL_GPI or INCL_PM */ 


LONG GpiSetClipRegion (HPS hps, HRGN hrgn, PHRGN phrgnOld) 


This function defines the region to be used for clipping, when any drawing takes place through the 
specified presentation space. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

The presentation space must be currently associated with a device context of the correct device 
class (defined when the region is first created). 

hrgn (HRGN) - input 
Region handle. 

If hrgn is null, the clipping region is setto no clipping (its initial state). 

phrgnOld (PHRGN) - output 
Old region handle (if any): 

HRGN_ERROR Error 

NULLHANDLE Null handle (no region selected) 

Otherwise Old region handle. 


Returns 

Complexity of clipping and error indicators: 


The clipping complexity information includes the combined effects of: 

• Clip path 

• Viewing limits 

• Graphics field 

• Clip region 

• Visible region (windowing considerations). 

RGN_NULL Null region 

RGN_RECT Rectangular region 


RGN_COMPLEX Complex region 
RGNERROR Error. 


Possible returns from WinGetLastError 


PMERRJNVHPS 

PMERR_PS_BUSY 

PMERRINVHRGN 

PMERRHRGNBUSY 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid region handle was specified. 

An internal region busy error was detected. The region 
was locked by one thread during an attempt to access it 
from another thread. 
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GpiSetClipRegion 
Set Clip Region 


Remarks 

While a region is in use as a clip region, the calls GpiOffsetClipRegion, GpiExcludeClipRectangle and 
GpilntersectClipRectangle cause it to be changed. These changes persist after the region has been 
deselected. The clip region cannot, however, be used for any other region operations, nor can it be 
selected into any other presentation space as a clipping region, until it is deselected. 

The coordinates of the region are taken to be device coordinates within the device context. 

The previous clip region, if any, is converted to a region, and a handle to it is returned. This can be 
used in a subsequent GpiSetClipRegion to reinstate the same clipping as before. If no clip region 
exists, a null handle is returned. It is the responsibility of the application to free the previous clip 
region (if any) with GpiDestroyRegion, even if this region was not originally created explicitly by the 
application. 

Note: This function must not be used when creating SAA-conforming metafiles; see “Metafile 
Restrictions” on page G-1 . 

Related Functions 

• GpiCreateRegion 

• GpiExcludeClipRectangle 

• GpilntersectClipRectangle 

• GpiOffsetClipRegion 

• GpiPtVisible 

• GpiQueryClipBox 

• GpiQueryClipRegion 

• GpiRectVisible 

• WinExcludellpdateRegion 
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GpiSetColor - 
Set Color 


#define INCLJ3PIPRIMITIVES /* Or use INCL_GPI or INCL_PM. Also in COMMON section */ 


BOOL GpiSetColor (HPS hps, LONG IColor) 


This function sets the current value of the color attribute for each of the individual primitive types. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

IColor (LONG) - input 
Color: 


CLR_FALSE 

CLRTRUE 

CLRDEFAULT 


CLR_ WHITE 
CLRBLACK 


All color planes are Os. 

All color planes are Is. 

Set to default value. This is a device-dependent color which, for the 
default color table, provides a contrasting color to CLR_BACKGROUND 
For a display, it is the default window text color (SYSCLR_WINDOWTEXT: 
see WinSetSysColors). For a printer, it is a color that contrasts with the 
paper color. The default can be changed by setting new system colors 
from the control panel for the display, or by selecting a paper color for a 
printer, if allowed by the device driver. It can also be set explicitly, using 
GpiSetDefAttrs. 

White (default color table, or index=RGB loaded color table). For a 
loaded, realized, color table it is the nearest available color to white. 

Black (default color table, or index=RGB loaded color table). For a 
loaded, realized, color table, it is the nearest available color to black. 


CLR_BACKGROUND Reset color, used by GpiErase. This is the natural background color for 
the device. For a display, it is the default window color 
(SYSCLR_WINDOW: see WinSetSysColors) for the default color table. For 
a printer, it is the paper color. For a loaded color table, it is color index 
0. For an RGB color table, it is color 000000 (black). 

CLR_BLUE Blue (default color table). 

CLR_RED Red (default color table). 


CLR_PINK Pink (default color table). 

CLR_GREEN Green (default color table). 


CLR_CYAN 


Cyan (default color table). 


CLR YELLOW Yellow (default color table). 

CLR_NEUTRAL Neutral (default color table). A device-dependent color, that for the 

default color table provides a contrasting color to CLR_BACKGROUND. 
For a display, it is the default window text color (SYSCLR_WINDOWTEXT: 
see WinSetSysColors). For a printer, it is a color that contrasts with the 
paper color. For a loaded color table, it is color index 7; in RGB mode it 
is interpreted as color 000007. 


CLR_DARKGRAY Dark gray (default color table). 
CLR_DARKBLUE Dark blue (default color table). 
CLR_DARKRED Dark red (default color table). 
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GpiSetColor 
Set Color 


CLRDARKPINK 

CLRDARKGREEN 

CLRDARKCYAN 

CLRBROWN 

CLRPALEGRAY 


Dark pink (default color table). 

Dark green (default color table). 

Dark cyan (default color table). 

Brown (default color table). 

Pale gray (default color table). 

For a loadable color table, values 0 through n correspond to the color 
index (or RGB) values. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 

PMERRJNV_HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_COLOR_ATTR An invalid color attribute value was specified or the 

defaujt value was explicitly specified with GpiSetAttrs 
instead of using the defaults mask. 

Remarks 

The current values for each primitive type are updated. The attribute mode (see GpiSetAttrMode) 
determines whether the current values of the individual color attributes are preserved. If so, they 
are restored by a single GpiPop function. 

An attempt to set a negative color value, other than one for which a constant is defined, causes the 
error PMERR_INV_COLOR_ATTR to be logged. Other color values are allowed, although an error is 
generated when the color value is needed for drawing if it is not valid for the color table in use at that 
time (see GpiCreateLogColorTable). 

For details of how colors are handled on monochrome devices, see GpiCreateLogColorTable. 


Related Functions 

• GpiQueryColor 

• GpiSetBackColor 

• GpiSetBackMix 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiSetMix 

• WinSetSysColors 
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Set Color 


Graphic Elements and Orders 

Element Type: OCODE_GSICOL 

This element type is generated if the attribute mode (see GpiSetAttrMode) is set to 
AM_NOPRESERVE. 

Order: Set Indexed Color 

Element Type: OCODE_GPSICOL 

This element type is generated if the attribute mode is set to AM_PRESERVE. 
Order: Push and Set Indexed Color 

Example Code 

This example draws a blue line. 

Idefine I NCL_GPI PRIMITIVES 
linclude <0S2.H> 


HPS hps; /* Presentation space handle */ 

POINTL ptl 1, ptl 2 ; 

GpiSetColor(hps, CLR_BLUE); 

GpiMove( hps, &ptll ); /* Move to start point */ 

Gpi Li ne ( hps, &ptl2 ); /* Draw new line */ 
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GpiSetCp - 
Set Code Page 


#define INCL_GPILCIDS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetCp (HPS hps, ULONG ulCodePage) 


This function sets the default graphics code page. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

ulCodePage (ULONG) - input 
Code-page identifier. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRJNVHPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERRJNV_CODEPAGE An invalid code-page parameter was specified with 

GpiSetCp. 

Remarks 

The default graphics code page is used for the default font (unless it is overridden by 
GpiCreateLogFont). It is also used for other fonts for which the usCodePage field in the FATTRS 
structure for GpiCreateLogFont is specified as 0. This includes existing fonts that are defined in this 
way. 

Any code page that is defined in the CONFIG.SYS file, or is a supported EBCDIC code page, can be 
selected. 

The list of available code pages is returned by WinQueryCpList. 

When a GPI presentation space is first created, the code page in force is that defined by the process 
code page. 

If this function occurs within a path definition when the drawing mode (see GpiSetDrawingMode) is 
retain or draw-and-retain, its effect is not stored with the definition. 

Note: There are restrictions on the use of this function when creating SAA-conforming metafiles; 
see “Metafile Restrictions” on page G-1. 
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GpiSetCp - 
Set Code Page 


Related Functions 

The DOS calls DosGetCp, DosSetCp, and DosSetProcCp are related to GpiSetCP, but they are not a 
part of the Presentation Manager, for more information on the mentioned DOS calls refer to the 
Control Program Reference. 

• GpiQueryCurrentPosition 

• GpiQueryCurrentPosition 

• GpiCreateLogFont 

• WinCpTranslateChar 

• WinCpTranslateString 

• WinQueryCp 

• WinQueryCpList 

• WinSetCp 

Example Code 

This example sets the code page to 850. 

Idefine INCL_GPI LCIDS 
linclude <0S2.H> 


HPS hps; /* Presentation space handle */ 
ULONG ul CodePage = 850; 

GpiSetCp(hps, ul CodePage); 
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GpiSetCurrentPosition 
Set Current Position 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetCurrentPosition (HPS hps, PPOINTL pptiPoint) 


This function sets the current position to the specified point. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

pptiPoint (PPOINTL) - input 

New value of current position. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERR_INV_HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERRJNV_COORDINATE An invalid coordinate value was specified. 

Remarks 

This function also has the effect of resetting the position within a line-type sequence, and, if within an 
area, of starting a new closed figure and causing any previous one to be closed if necessary. 

This function is equivalent to the GpiMove function except that, if the current attribute mode is 
AM_PRESERVE (see GpiSetAttrMode), the current position is saved before being set to the new 
value, so that it can be restored using the GpiPop function; 


Related Functions 

• GpiMove 

• GpiQueryCurrentPosition 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

Graphic Elements and Orders 

Element Type: OCODE_GSCP 

This element type is generated if the attribute mode (see GpiSetAttrMode) is set to 
AM_NOPRESERVE. 

Order: Set Current Position 

Element Type: OCODE_GPSCP 

This element type is generated if the attribute mode is set to AM PRESERVE. 

Order: Push and Set Current Position 
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Set Current Position 


Example Code 

The position of the top-left corner of the window rectangle is recorded and selected as the current 
position before the image is drawn. 

Idefine INCL_GPIPRIMITIVES 
linclude <0S2.H> 

HPS hps; /* Presentation space handle */ 

HWND hwndClient; /* client window handle. */ 

RECTL rcl ; 

POINTL vptlSave; 


WinQueryWindowRect(hwndCl ient, &rcl ) ; 
vptlSave. x = rcl.xLeft; 
vptlSave.y = rcl.yTop; 

Gpi SetCurrentPosi ti on(hps , &vptl Save) ; 
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GpiSetDefArcParams - 
Set Default Arc Parameters 


#define INCL_GPIDEFAULTS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetDefArcParams (HPS hps, PARCPARAMS parcpArcParams) 


This function specifies the default values of the arc parameters (see GpiSetArcParams). 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

parcpArcParams (PARCPARAMS) - input 
Default arc parameters. 

This structure has four elements p, q, r, and s. 

Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRJNVHPS 
PMERRPSBUSY 

PMERRINVCOORDINATE 

Remarks 

The arc parameters are reset to their default values at the following times: 

• When the presentation space is associated with a device context (see GpiAssociate). 

• When GpiResetPS is issued. 

• When drawing of a chained segment begins or ends (see GpiOpenSegment and 
GpiCloseSegment for more details). 

The initial default values of the arc parameters, when the presentation space is first created, are : 

p = 1 r = 0 

s = 0 q = 1 

The default values can be changed by GpiSetDefArcParams. Changing the default values has an 
immediate effect on the current arc parameters, if these are currently set to the default value. 

See “GpiSetArcParams - Set Arc Parameters” on page 5-398 for a description of the arc 
parameters. 

Note: There are restrictions on the use of this function when creating SAA-conforming metafiles; 
see “Metafile Restrictions” on page G-1. 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid coordinate value was specified. 
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GpiSetDefArcParams - 
Set Default Arc Parameters 


Related Functions 

• GpiFullArc 

• GpiPartialArc 

• GpiPointArc 

• GpiQueryDefArcParams 

• GpiSetArcParams 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

Example Code 

This function specifies the default values of the arc parameters (see GpiSetArcParams). 

Idefine INCL_GPIDEFAULTS 
Idefine INCL_GPIPRIMITIVES 
linclude <0S2.H> 


HPS hps; /* Presentation space handle */ 

ARCPARAMS ArcParams = {10L, /* p */ 

20L, /* q */ 

10L, /* r */ 

30L}; /* 1 */ 

/* This structure has four */ 
/* elements p, q, r, and s. */ 


GpiSetDefArcParams (hps, &ArcParams) ; 
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GpiSetDefAttrs - 
Set Default Attributes 


#define INCL_GPIDEFAULTS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetDefAttrs (HPS hps, LONG IPrimType, ULONG fiAttrMask, PBUNDLE ppbunAttrs) 


This function sets the default values of attributes for the specified primitive type. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

IPrimType (LONG) - input 
Primitive type. 

The primitive type for which default attributes are to be set: 


PRIMJJNE 
PRIMCHAR 
PRIMMARKER 
PRIMAREA 
PRIMIMAGE 
fiAttrMask (ULONG) 


Line and arc primitives 
Character primitives 
Marker primitives 
Area primitives 
Image primitives. 

- input 


Attributes mask. 

Each flag that is set indicates that the ppbunAttrs buffer contains data for the corresponding 
attribute. If all the flags in fiAttrMask are 0, the ppbunAttrs buffer address is not used. 

Line attributes: 


LBB_COLOR 

LBBMIXMODE 

LBB WIDTH 

LBBGEOMWIDTH 

LBB_TYPE 

LBB END 

LBB_JOIN 

Character attributes: 


Line color 
Line mix 
Line width 

Geometric line width 
Line type 
Line end 
Line join. 


CBB_COLOR 

CBBBACKCOLOR 

CBBMIXMODE 

CBBBACKMIXMODE 

CBBSET 

CBB MODE 

CBBBOX 

CBBANGLE 

CBBSHEAR 

CBBDIRECTION 


Character color 
Character background color 
Character mix 
Character background mix 
Character set 
Character mode 
Character box 
Character angle 
Character shear 
Character direction 
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Set Default Attributes 


CBB_EXTRA 

Character extra 

CBBBREAKEXTRA 

Character extra 

Marker attributes: 


MBBCOLOR 

Marker color 

MBBBACKCOLOR 

Marker background color 

MBB MIX MODE 

Marker mix 

M BBBACKMIXMODE 

Marker background mix 

MBB SET 

Marker set 

MBB_SYMBOL 

Marker symbol 

MBBBOX 

Marker box. 

Pattern attributes (areas): 


ABB_COLOR 

Area color 

ABBBACKCOLOR 

Area background color 

ABBMIXMODE 

Area mix 

ABB_BACK_MIX_MODE 

Area background mix 

ABBSET 

Pattern set 

ABBSYMBOL 

Pattern symbol 

ABBREFPOINT 

Pattern reference point. 

Image attributes: 


IBBCOLOR 

Image color 

IBBBACKCOLOR 

Image background color 

IBBMIXMODE 

Image mix 

IBBBACKMIXMODE 

Image background mix. 


ppbunAttrs (PBUNDLE) - input 
Default attribute values. 

This is a structure containing default attribute values for each attribute for which the flAttrMask 
flag is set, at the correct offset as specified below for the particular primitive type. 

Line attributes: ppbunAttrs consists of a LINEBUNDLE structure. 

Character attributes: ppbunAttrs consists of a CHARBUNDLE structure. 

Marker attributes: ppbunAttrs consists of a MARKERBUNDLE structure. 

Pattern attributes (areas): ppbunAttrs consists of an AREABUNDLE structure. 

Image attributes: ppbunAttrs consists of an IMAGEBUNDLE structure. 

Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRJNVHPS 
PMERRPSBUSY 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 
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Set Default Attributes 



1 

P M E R R_IN V_P RIM ITI VE_T YPE 

An invalid primitive type parameter was specified with 

GpiSetAttrs or GpiQueryAttrs. 


— 

PMERRUNSUPPORTEDATTR 

An unsupported attribute was specified in the attrmask 
with GpiSetAttrs or GpiQueryAttrs. 



PMERRJNVCOLORATTR 

An invalid color attribute value was specified or the 
default value was explicitly specified with GpiSetAttrs 
instead of using the defaults mask. 



PMERRINVBACKGROUNDCOLATTR 

An invalid background color attribute value was specified 
or the default value was explicitly specified with 

GpiSetAttrs instead of using the defaults mask. 



PMERR_INV_MIX_ATTR 

An invalid mix attribute value was specified or the default 
value was explicitly specified with GpiSetAttrs instead of 
using the defaults mask. 



P M E R R IN V LIN E_WIDTH_ ATTR 

An invalid line width attribute value was specified or the 
default value was explicitly specified with GpiSetAttrs 
instead of using the defaults mask. 



PMERR_INV_GEOM_LINE_WIDTH_ATTR 

An invalid geometric line width attribute value was 
specified. 



PMERR_INV_LINE_TYPE_ATTR 

An invalid line type attribute value was specified or the 
default value was explicitly specified with GpiSetAttrs 
instead of using the defaults mask. 


— 

PMERR_INV_LINE_END_ATTR 

An invalid line end attribute value was specified. 



P M ER R_IN V_LINE_ JOI N_ ATTR 

An invalid line join attribute value was specified. 

— - 

' 

P M ER R_IN V_CH A R_SET_ATTR 

An invalid character setid attribute value was specified or 
the default value was explicitly specified with GpiSetAttrs 
instead of using the defaults mask. 




PMERR_INV_CHAR_MODE_ATTR 

An invalid character mode attribute value was specified 
or the default value was explicitly specified with 

GpiSetAttrs instead of using the defaults mask. 



PMERR_INV_CHAR_DIRECTION_ATTR 

An invalid character direction attribute value was 
specified or the default value was explicitly specified with 
GpiSetAttrs instead of using the defaults mask. 



PMERR_INV_CHAR_SHEAR_ATTR 

An invalid character shear attribute value was specified 
or the default value was explicitly specified with 

GpiSetAttrs instead of using the defaults mask. 



PMERR_INV_CHAR_ANGLE_ATTR 

The default character angle attribute value was explicitly 
specified with GpiSetAttrs instead of using the defaults 
mask. 



PMERR_INV_MARKER_SET_ATTR 

An invalid marker set attribute value was specified or the 
default value was explicitly specified with GpiSetAttrs 
instead of using the defaults mask. 



P M E R R IN V_M A R K E R_S YM BOL_ ATTR 

An invalid marker symbol attribute value was specified or 
the default value was explicitly specified with GpiSetAttrs 
instead of using the defaults mask. 



PM E R R _IN VP ATTER N_SET_ATTR 

An invalid pattern set attribute value was specified or the 
default value was explicitly specified with GpiSetAttrs 
instead of using the defaults mask. 



PMERR_INV_PATTERN_ATTR 

An invalid pattern symbol attribute value was specified or 
the default value was explicitly specified with GpiSetAttrs 




instead of using the defaults mask. 
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Set Default Attributes 


PMERR_INV_COORDINATE An invalid coordinate value was specified. 

PMERR_UNSUPPORTED_ATTR_VALUE An attribute value was specified with GpiSetAttrs that is 

not supported. 


PMERR_INV_PATTERN_SET_FONT An attempt was made to use an unsuitable font as a 

pattern set. 

PMERR_HUGE_FONTS_NOT_SUPPORTED An attempt was made using GpiSetCharSet, 

GpiSetPatternSet, GpiSetMarkerSet, or GpiSetAttrs to 
select a font that is larger than the maximum size (64Kb) 
supported by the target device driver. 


Remarks 

Attributes are reset to their default values at the following times: 

• When the presentation space is associated with a device context (see Gpi Associate). 

• When GpiResetPS is issued. 

• When drawing of a chained segment begins or ends (see GpiOpenSegment and 
GpiCloseSegment for more details). 

• When an attribute-setting function (for example, GpiSetAttrs) that sets an attribute to its default 
value is issued, or interpreted in a retained segment during a drawing operation. 

Each attribute has an initial default value, established when the presentation space is first created. 
The value of this is given under the appropriate GpiSet... call. The default value can be changed by 
GpiSetDefAttrs. Changing the default value takes effect immediately for the current value, if this is 
set to default at the time. 

Each attribute of the primitive type in question is represented by one flag in the flAttrMask 
parameter. Any attribute for which the appropriate flag is set has its default value updated to the 
value specified in the ppbunAttrs structure. If the attribute is currently set to take the default value, it 
is immediately assigned the new default value. The default value of any attribute for which the 
appropriate flag in flAttrMask is not set is unchanged. 

The data in the ppbunAttrs buffer consists of a structure of attribute data. The layout of the structure 
is fixed for each primitive type. Only data for attributes for which the flag is set in flAttrMask is 
inspected; any other data is ignored. 

Note: The buffer need be no longer than is necessary to contain the data for the highest offset 
attribute referenced. 

If an attempt is made to set an invalid default value by this function, none of the specified default 
attribute values is changed. Note, however, that some invalid default attribute values (for example, 
certain color and mix values) may not be detected until the attribute is setto default and used, at 
which point the implementation optionally defaults them, or causes an error to be logged. 

Note: There are restrictions on the use of this function when creating SAA-conforming metafiles; 
see "Metafile Restrictions" on page G-1. Also, in a metafile, the default line width (see 
GpiSetLineWidth) is always rounded to an integer value, as is the default character box (see 
GpiSetCharBox) for GPIF_SHORT format presentation spaces (see GpiCreatePS). 
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Set Default Attributes 


Example Code 

This function sets the default color of line and arc primitives to blue. 
Idefine INCL.GPIDEFAULTS 

Idefine INCL_GPI PRIMITIVES /* for parameter definitions */ 
linclude <0S2.H> 

HPS hps; /* Presentation space handle */ 

LINEBUNDLE bunAttrs; /* Information for color */ 

bunAttrs.lColor = CLR_BLUE; 


GpiSetDefAttrs (hps, 

PRIM LINE, /* line and arc primitives. */ 

LBB_C0L0R, /* color information, which is */ 

/* contained in bunAttrs */ 

&bunAttrs) ; 
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GpiSetDefauItViewMatrix - 
Set Default View Matrix 


#define INCL_GPITRANSFORMS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetDefauItViewMatrix (HPS hps, LONG ICount, PMATRIXLF pmatlfarray, 

LONG lOptlons) 


This function sets the default viewing transform that is to apply to the whole picture. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

ICount (LONG) - input 
Number of elements. 


The number of elements supplied in pmatlfarray, that are to be examined, starting from the 
beginning of the structure. If ICount is less than 9, remaining elements default to the 
corresponding elements of the identity matrix. Specifying ICount = 0 means that the identity 
matrix is used. 

pmatlfarray (PMATRIXLF) - input 
Transformation matrix. 


The elements of the transform, in row order. The first, second, fourth, and fifth elements are of 
type FIXED, and have an assumed binary point between the second and third bytes. Thus a 
value of 1.0 is represented by 65 536. Other elements are normal signed integers. If the 
presentation-space coordinate format is GPfF SHORT (see GpiCreatePS), these elements must 
be within the range —1 through +1. 

The third, sixth, and ninth elements, when specified, must be 0, 0, and 1, respectively. 

lOptlons (LONG) - input 
Transform options. 

Specifies how the transform defined by the pmatlfarray parameter should be used to modify the 
existing default viewing transform. 

Possible values are: 


TRANSFORM_REPLACE The previous default viewing transform is discarded and replaced by 

the specified transform. 

TRANSFORM_ADD The specified transform is combined with the existing default viewing 

transform, in the order (1) existing transform, (2) new transform. This 
option is most useful for incremental updates to transforms. 


TRANSFORM_PREEMPT The specified transform is combined with the existing default viewing 

transform, in the order (1) new transform, (2) existing transform. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERR INV HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 
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GpiSetDefauItViewMatrix 
Set Default View Matrix 


PMERR_INV_LENGTH_OR_COUNT An invalid length or count parameter was specified. 

PMERRJNV_TRANSFORM_TYPE An invalid options parameter was specified with a 

transform matrix function. 

PMERR_INV_MATRIX_ELEMENT An invalid transformation matrix element was specified. 

Remarks 

The transform matrix specified is used to update any previous default viewing transform, depending 
upon the value of / Options . 

The transform is specified as a one-dimensional array of I Count elements, being the first n elements 
of a 3-row by 3-column matrix ordered by rows. The order of the elements is: 

Matrix Array 


a b 0 
c d 0 
e f 1 


(a,b,0,c,d,0,e,f ,1) 


The transform acts on the coordinates of the primitives in a segment, so that a point with coordinates 
(x,y) is transformed to the point: 

(a*x + c*y + e, b*x + d*y + f) 

The initial value of the default viewing transform is the identity matrix, as shown below: 

Matrix Array 


1 0 0 
0 1 0 
0 0 1 


( 1 , 0 , 0 , 0 , 1 , 0 , 0 , 0 , 1 ) 


If scaling values greater than unity are given (which only applies if the presentation space coordinate 
format, as set by the GpiCreatePS function, is GPIF_LONG), it is possible for the combined effect of 
this and any other relevant transforms to exceed fixed-point implementation limits. This causes an 
error. 

This function must not be issued in a path or area bracket. 

Note: There are restrictions on the use of this function when creating SAA-conform i ng metafiles; 
see “Metafile Restrictions” on page G-1. 

Related Functions 

• GpiQueryDefauItViewMatrix 

• GpiSetViewingTransformMatrix 
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Set Default View Matrix 


Example Code 

This example uses the GpiSetDefauItViewMatrix function to replace the existing default viewing 
transformation. The new transformation translates drawing to the right by 100 units. 

Idefine INCL_GPITRANSFORMS /* Transform functions */ 

linclude <os2.h> 

BOOL f Success; /* success indicator */ 

HPS hps; /* Presentation-space handle */ 

/* transform matrix */ 

MATRIXLF matlf = {MAKEFIXED (1,0) , 0, 0, 0, MAKEFIXED(l.O) , 0, 100}; 

f Success = GpiSetDefaultViewMatrix(hps, 7L, Smatlf, 

TRANSF0RM_REPLACE) ; 
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GpiSetDefTag - 
Set Default Tag 


#define INCL_GPIDEFAULTS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetDefTag (HPS hps, LONG ITag) 


This function specifies the default value of the primitive tag (see GpiSetTag). 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

ITag (LONG) - input 
Default tag identifier. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERR_INV_HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_MICROPS_FUNCTION An attempt was made to issue a function that is invalid in 

a micro presentation space. 

Remarks 

The primitive tag is reset to its default value at the following times: 

• When the presentation space is associated with a device context (see Gpi Associate). 

• When GpiResetPS is issued. 

• When drawing of a chained segment begins or ends (see GpiOpenSegment and 
GpiCloseSegment for more details). 

The initial default value of the primitive tag, when the presentation space is first created, is 0. The 
default value can be changed by GpiSetDefTag. Changing the default value has an immediate effect 
on the current primitive tag, if this is currently set to the default value. 

Note: There are restrictions on the use of this function when creating SAA-conforming metafiles; 
see “Metafile Restrictions” on page G-1. 

Related Functions 

• GpiQueryDefAttrs 

• GpiQueryTag 

• GpiSetTag 
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GpiSetDefTag - 
Set Default Tag 


Example Code 

This function specifies the default value of the primitive tag (see GpiSetTag). 

Idefine INCL_GPI PRIMITIVES 
linclude <0S2.H> 

HPS hps; /* Presentation space handle */ 

GpiSetDefTag (hps, 1L); 
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Set Default Viewing Limits 


#define INCL_GPIDEFAULTS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetDefViewingLimits (HPS hps, PRECTL prcILimlts) 


This function specifies the default value of the viewing limits (see GpiSetViewingLimits). 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

prciLimits (PRECTL) - input 
Default viewing limits. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERR_INV_HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_COORDINATE An invalid coordinate value was specified. 

Remarks 

The viewing limits are reset to their default value at the following times: 

• When the presentation space is associated with a device context (see GpiAssociate). 

• When GpiResetPS is issued. 

• When drawing of a chained segment begins or ends (see GpiOpenSegment and 
GpiCloseSegment for more details). 

The initial default value of the viewing limits, when the presentation space is first created, is no 
clipping. The default value can be changed by GpiSetDefViewingLimits. Changing the default values 
has an immediate effect on the current viewing limits, if these are currently set to the default value. 

Note: There are restrictions on the use of this function when creating SAA-conforming metafiles; 
see “Metafile Restrictions” on page G-1. 

Related Functions 

• GpiQueryDefViewingLimits 

• GpiQueryGraphicsField 

• GpiQueryViewingLimits 

• GpiSetGraphicsField 

• GpiSetViewingLimits 


5-472 


PM Programming Reference 




GpiSetDefViewingLimits - 
Set Default Viewing Limits 


Example Code 

In this example the default model space clipping region width is set to 100. 


Idefine INCL_GPI PRIMITIVES 
linclude <0S2.H> 

HPS hps; /* Presentation-space */ 

/* handle. */ 

RECTL rcl Limits; /* viewing limits. */ 


rclLimits.xRight = 100; 
rclLimits.xLeft = 100; 

Gpi SetDefVi ewi ngLimi ts (hps , 

&rcl Limits); 
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GpiSetDrawControl 
Set Draw Control 


^define INCL_GPICONTROL /* Or use INCL_GPI or INCL_PM 7 


BOOL GpiSetDrawControl (HPS hps, LONG IControl, LONG IValue) 


This function sets options for subsequent drawing operations. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

IControl (LONG) - input 
Drawing control. 

Note: Controls identified by an asterisk (*) are the only ones relevant to a micro-presentation 
space. Any other control settings are ignored for a micro-presentation space. 

Erase before draw. Perform an implicit GpiErase operation before 
GpiDrawChain, GpiDrawFrom, or GpiDrawSegment. The output 
display area of the Device Context associated with the specified 
presentation space is cleared before drawing. 

Enable drawing to occur on the output medium. If this control is set to 
off, then except for GpiErase, no output operations appear on the 
output medium. This includes raster operations, such as drawing 
primitives, and GpiDraw... operations. 

Accumulate boundary data. During any output operations except 
GpiErase, accumulate the bounding rectangle of the drawing. 

Draw dynamic segments. Perform an implicit GpiRemoveDynamics 
before GpiDrawChain, GpiDrawFrom, or GpiDrawSegment, and an 
implicit GpiDrawDynamics afterwards. 

Note that, to either remove or draw dynamic segments, the system 
forces the foreground mix to FM_XOR, and the background mix to 
BM_LEAVEALONE. If the first nondynamic segment being drawn 
(immediately after the dynamic segments have been removed) has the 
ATTR_FASTCHAIN attribute (see GpiSetlnitialSegmentAttrs), it may be 
necessary for it to set the mix modes itself before drawing. Similar 
considerations might apply for any subsequent drawing after the 
dynamic segments have been replaced. 

DCTL_CORRELATE (*) If this control is set, any GpiPutData, GpiElement, GpiPlayMetaFile, or 
individual drawing primitives which are passed across the API outside 
a segment bracket cause a correlation operation to be performed, and 
a return code to be set if a hit occurs. (Correlation inside segments, 
both retained and nonretained, is controlled by the segment attribute 
ATTR_DETECTABLE). 

This control has an effect only in draw or draw-and-retain modes (see 
GpiSetDrawingMode). 


DCTLERASE 

DCTL_DISPLAY (*) 

DCTL BOUNDARY (*) 
DCTLDYNAMIC 


IValue (LONG) - input 

Required value of the drawing control: 

DCTL_OFF Set control off 

DCTL_ON Set control on. 
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GpiSetDrawControl - 
Set Draw Control 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred; 


Possible returns from WinGetLastError 


PMERRINVHPS 

PMERR_PS_BUSY 

PMERRINVDRAWCONTROL 

PMERR_INV_DRAW_ VALUE 

PMERRINVINSEG 

PMERRJNVJNAREA 

PM E R R_IN V_IN_P ATH 
PMERRINVINELEMENT 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid control parameter was specified with 
GpiSetDrawControl or GpiQueryDrawControl. 

An invalid value parameter was specified with 
GpiSetDrawControl . 

An attempt was made to issue a function invalid inside a 
segment bracket. 

An attempt was made to issue a function invalid inside an 
area bracket. This can be detected while the actual 
drawing mode is draw or draw-and-retaln or during 
segment drawing or correlation functions. 

An attempt was made to issue a function invalid inside a 
path bracket. 

An attempt was made to issue a function invalid inside an 
element bracket. 


PMERR_INV_MICROPS_DRAW_CONTROL A draw control parameter was specified with 

GpiSetDrawControl that is invalid in a micro presentation 
space. 


Remarks 

The default value is DCTL_OFF for all controls except DCTL_DISPLAY (*). Its default value is 
DCTL_ON. 

This function must not be issued in any of these cases: 

• Inside an open segment 

• Outside an open segment, but inside one of: 

- Area bracket 

- Element bracket 

- Path bracket. 

Note: There are restrictions on the use of this function when creating SAA-conforming metafiles; 
see “Metafile Restrictions” on page G-1. 
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GpiSetDrawControl - 
Set Draw Control 

Related Functions 

• GpiDrawChain 

• GpiDrawDynamics 

• GpiDrawFrom 

• GpiDrawSegment 

• GpiErase 

• GpiQueryDrawControl 

• GpiQueryDrawingMode 

• GpiQueryStopDraw 

• GpiRemoveDynamics 

• GpiSetDrawingMode 

• GpiSetStopDraw 

Example Code 

The “display" drawing control is switched off, and the “accumulate-boundary-data” control is 
switched on. 

Idefine INCL_GPICONTROL 
linclude <0S2.H> 

HPS hps; /* Presentation-space */ 

/* handle. */ 

GpiResetBoundaryData(hps) ; 

GpiSetDrawControl (hps, DCTL_DISPLAY, DCTL_0FF); 
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GpiSetDrawingMode - 
Set Drawing Mode 


#define INCL_GPICONTROL /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetDrawingMode (HPS hps, LONG IMode) 


This function sets the drawing mode to control the handling of subsequent individual drawing 
primitive and attribute calls. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

IMode (LONG) - input 

Mode to be used for subsequent drawing calls: 

DM_DRAW Draw, unless in an unchained segment 

DM_RETAIN Retain, if within a segment 

DM_DRAWANDRETAIN Draw-and-retain, combination of above. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 


PMERRINVHPS 

PMERRPSBUSY 

PMERRINVMICROPSFUNCTION 

PMERRINVINAREA 

PMERRJNVJN_PATH 

PMERR_INVJN_ELEMENT 

PMERRINVJNSEG 

PMERRINVDRAWINGMODE 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An attempt was made to issue a function that is invalid in 
a micro presentation space. 

An attempt was made to issue a function invalid inside an 
area bracket. This can be detected while the actual 
drawing mode is draw or draw-and-retain or during 
segment drawing or correlation functions. 

An attempt was made to issue a function invalid inside a 
path bracket. 

An attempt was made to issue a function invalid inside an 
element bracket. 

An attempt was made to issue a function invalid inside a 
segment bracket. 

An invalid mode parameter was specified with 
GpiSetDrawControl not draw-and-retain or draw. 
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GpiSetDrawingMode 
Set Drawing Mode 


Remarks 

The drawing mode affects the handling of subsequent individual drawing primitive and attribute calls, 
and the GpiPutData, GpiElement, and GpiPlayMetaFile functions. 

Primitives and attributes can be drawn immediately, retained, or both, in the current segment. 

Note: Any primitive and attribute setting calls that occur outside a segment (that is, outside a 
GpiOpenSegment — GpiCloseSegment bracket} are always treated as nonretained. 
Conversely, any segments that are not chained are always retained. This table summarizes 
how the actual drawing mode is arrived at: 


GpiSetDrawingMode 

Parameter 

Context 

Chained 

Segment 

Unchained 

Segment 

Outside 

Segment 

DM_DRAWANDRETAIN 

draw-and-retain 

retain 

draw 

DM_RETAIN 

retain 

retain 

draw 

DM_DRAW 

draw 

retain 

draw 


The actual drawing mode (referred to when describing other Gpi calls) therefore depends upon the 
mode as set by GpiSetDrawingMode, together with the context, as in the table. It is this actual 
drawing mode that determines whether a drawing call is retained (retain or draw-and-retain), and 
whether it is drawn immediately (draw or draw-and-retain). 

It is an error to try to set the drawing mode within a segment bracket, and also outside a segment 
bracket, if in one of the following: 

• Area bracket 

• Element bracket 

• Path bracket. 

The default drawing mode is DM_DRAW. 


Related Functions 

• GpiDrawChain 

• GpiDrawDynamics 

• GpiDrawFrom 

• GpiDrawSegment 

• GpiErase 

• GpiGetData 

• GpiOpenSegment 

• GpiPutData 

• GpiQueryDrawControl 

• GpiQueryDrawingMode 

• GpiQueryStopDraw 

• GpiRemoveDynamics 

• GpiSetStopDraw 

• GpiOpenSegment 
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GpiSetDrawingMode - 
Set Drawing Mode 


Example Code 

This example calls GpiSetDrawingMode to set the drawing mode to DRAW. 

Idefine INCL_GPICONTROL /* GPI control Functions */ 

linclude <os2.h> 

BOOL fSuccess; /* success indicator */ 

HPS hps; /* Presentation-space handle */ 

fSuccess = GpiSetDrawingMode (hps, DM_DRAW); 
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GpiSetEditMode 
Set Edit Mode 


#define INCL_GPISEGEDITING /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetEditMode (HPS hps, LONG IMode) 


This function sets the current editing mode. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

IMode (LONG) - input 
Edit mode: 

SEGEMJNSERT Insert mode 
SEGEM_REPLACE Replace mode. 

Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRINVHPS 
PMERRPSBUSY 

PMERRINVEDITMODE 

PMERRJNVJNELEMENT 

PMERR INV_MICROPS_FUNCTION An attempt was made to issue a function that is invalid in 

a micro presentation space. 

Remarks 

This function determines whether a new element is to be inserted into a segment, moving any 
subsequent elements further along the segment, or whether a new element is to replace the current 
element. 

In SEGEMJNSERT mode, when an element is generated, it is inserted following the element 
indicated by the element pointer. The element pointer is updated to point to the new element. 

In SEGEM_REPLACE mode, when an element is generated, it replaces the element indicated by the 
element pointer. The element pointer does not change. It is an error if a new element is generated 
in SEGEM_REPLACE mode if the element pointer is 0 (as it is when a segment is opened). 

The editing mode can be changed at any time, (except while within an element bracket), and is not an 
attribute of a specific segment. It only applies to the storing of data within retained segments. It is 
not an error to issue this function in other drawing modes; the value of the edit mode is set 
irrespective of the value of the draw mode. 

This function is invalid within an element bracket. The default editing mode (set by GpiCreatePS or 
GpiResetPS) is SEGEMJNSERT. 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid mode parameter was specified with 
GpiSetEditMode. 

An attempt was made to issue a function invalid inside an 
element bracket. 
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GpiSetEditMode - 
Set Edit Mode 


Related Functions 

• GpiCreatePS 

• GpiOpenSegment 

• GpiQueryEditMode 

Example Code 

This example sets the current editing mode to insert. 

Idefine INCL_GPISEGEDITING 
linclude <0S2.H> 

HPS hps; /* Presentation-space */ 

/* handle. */ 

GpiSetEditMode (hps, SEGEM_INSERT) ; /* insert mode. */ 
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GpiSetElementPointer 
Set Element Pointer 


#define INCL_GPISEGEDITING /* Or use INCL_GPI or INCL_PM 7 


BOOL GpiSetElementPointer (HPS hps, LONG lElement) 


This function sets the element pointer, within the current segment, to the element number specified. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

lElement (LONG) - input 

The element number required. 

If the value specified is negative, the element pointer is set to 0. 

If the value specified is greater than the number of elements in the segment, the element pointer 
is set to the last element. 

Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRJNVHPS 
PMERRPSBUSY 

PMERR_NOT_IN_RET AINMODE 

PMERRNOCURRENTSEG 

PMERRJNVMICROPSFUNCTION 
PMERRINVINELEMENT 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An attempt was made to issue a segment editing element 
function that is invalid when the actual drawing mode is 
not set to retain 

An attempt has been made to issue 
GpiQueryElementType or GpiQueryElement while there is 
no currently open segment. 

An attempt was made to issue a function that is invalid in 
a micro presentation space. 

An attempt was made to issue a function invalid inside an 
element bracket. 


Remarks 

The currently open segment has an element pointer that points to a particular element in the 
segment; each element is placed into the segment at the place indicated by the pointer. When a 
retained segment is first opened, the element pointer is set to 0 (empty segment). It is incremented 
each time a call causes an element (a single API call) to be placed in the segment. When a segment 
is reopened, the element pointer is reset to 0 (that is, before the first element). 

The element pointer for a segment is not remembered if the segment is closed and subsequently 
reopened. 

This function is only valid when the drawing mode (see GpiSetDrawingMode) is set to retain (not 
draw-and-retain), and a segment bracket is currently in progress. It is invalid within an element 
bracket. 
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GpiSetElementPointer - 
Set Element Pointer 


Related Functions 

• GpiBeginElement 

• GpiDeleteElement 

• GpiDeleteElementRange 

• GpiDeleteElementsBetweenLabels 

• GpiElement 

• GpiEndElement 

• GpiLabel 

• GpiOffsetElementPointer 

• GpiQueryElement 

• GpiQueryElementPointer 

• GpiQueryElementType 

• GpiSetElementPointerAtLabel 

Example Code 

This function sets the element pointer, within the current segment, to 0. 

Idefine INCL_GPIC0NTR0L 
Idefine INCL_GPISEGEDITING 
linclude <0S2.H> 

HPS hps; /* Presentation-space */ 

/* handle. */ 


/* This example uses the GpiSetElementPointer function to move */ 
/* the element pointer to an element to be edited. */ 

GpiSetDrawingMode(hps, DMRETAIN) ;/* set DMRETAIN drawing mode */ 


GpiOpenSegment ( hps , 2L) ; 
GpiSetElementPointer(hps, 3L); 

GpiSetColor(hps,CLR_GREEN) ; 

Gpi Cl oseSegment (hps ) ; 


/* open segment to edit */ 
/* move element pointer 


to 3rd element 
/* new element changes 
color to green 
/* close the segment 


*/ 

*/ 
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GpiSetElementPointerAtLabel 
Set Element Pointer At Label 


^define INCL_GPISEGEDITING /* Or use INCL_GPI or INCL_PM 7 


BOOL GpiSetEiementPoInterAtLabel (HPS bps, LONG ILabei) 


This function sets the element pointer, within the current segment, to the element containing the 
specified label. 


Parameters 

bps (HPS) - input 

Presentation-space handle. 

ILabei (LONG) - input 
Required label. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 


PMERRJNVHPS 

PMERRPSBUSY 

PMERRINVMICROPSFUNCTION 

PMERR_NOT_IN_RETAIN_MODE 

PMERRNOCURRENTSEG 

PMERRINVJNELEMENT 

PMERRLABELNOTFOUND 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An attempt was made to issue a function that is invalid in 
a micro presentation space. 

An attempt was made to issue a segment editing element 
function that is invalid when the actual drawing mode is 
not set to retain 

An attempt has been made to issue 
GpiQueryElementType or GpiQueryElement while there is 
no currently open segment. 

An attempt was made to issue a function invalid inside an 
element bracket. 

The specified element label did not exist. 


Remarks 

The search starts from the element pointed to by the current element pointer. If the specified label is 
not found between there and the end of the segment, an error is generated and the element pointer is 
left unchanged. (Also see GpiSetElementPointer.) 

This function is valid only when the drawing mode (see GpiSetDrawingMode) is set to retain (not 
draw-and-retain), and a segment bracket is currently open. It is not valid within an element bracket. 
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GpiSetElementPointerAtLabel - 
Set Element Pointer At Label 


Related Functions 

• GpiBeginElement 

• GpiDeleteElement 

• GpiDeleteElementRange 

• GpiDeleteElementsBetweenLabels 

• GpiElement 

• GpiEndElement 

• GpiLabel 

• GpiOffsetElementPointer 

• GpiQueryElement 

• GpiQueryElementPointer 

• GpiQueryElementType 

• GpiSetElementPointer 

Example Code 

This function sets the element pointer at label 1. 

Idefine INCL_GPISEGEDITING 
linclude <0S2.H> 

HPS hps; /* Presentation-space */ 

/* handle. */ 

GpiSetElementPointerAtLabel (hps, 1L) ; 
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GpiSetGraphicsField 
Set Graphics Field 


#define I NCL_GPITRANSFORMS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetGraphicsField (HPS hps, PRECTL prciField) 


This function sets the size and position of the graphics field in presentation page units. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

prciField (PRECTL) - input 
Graphics field. 

It is an error if the top coordinate is less than the bottom, or the right coordinate is less than the 
left. 

All values are in presentation-page units. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 

PMERRINVHPS 

PMERR_PS_BUSY 

PMERRJNVGRAPHICSFIELD 

PMERRINVCOORDINATE 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid field parameter was specified with 
GpiSetGraphicsField 

An invalid coordinate value was specified. 


Remarks 

The graphics field specifies a clipping boundary within the presentation page. 

The boundaries are inclusive, so that points on them are not clipped (removed). By default, no 
clipping is performed. 

Note: There are restrictions on the use of this function when creating SAA-conforming metafiles; 
see “Metafile Restrictions” on page G-1. 
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GpiSetGraphicsField - 
Set Graphics Field 


Related Functions 

• GpiQueryDefViewingLimits 

• GpiQueryGraphicsField 

• GpiQueryViewingLimits 

• GpiSetDefViewingLimits 

• GpiSetViewingLimits 

• GpiExcludeClipRectangle 

• GpilntersectClipRectangle 

• GpiOffsetClipRegion 

• GpiQueryClipBox 

• GpiQueryClipRegion 

• GpiSetClipPath 

• GpiSetClipRegion 

Example Code 

This example sets the graphics field to 400 by 400 with the left bottom corner at 25,25. 

Idefine INCL_GPITRANSFORMS 
linclude <0S2.H> 

HPS hps; /* Presentation-space */ 

/* handle. */ 

RECTL rcl Field = {25, /* x coordinate of left-hand edge of */ 

/* rectangle. */ 

25, /* y coordinate of bottom edge of */ 

/* rectangle. */ 

425,/* x coordinate of right-hand edge of */ 

/* rectangle. */ 

425};/* y coordinate of top edge of rectangle. */ 


GpiSetGraphicsField(hps, &rcl Field) ; 
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GpiSetlnitialSegmentAttrs - 
Set Initial Segment Attributes 


#define INCL_GPISEGMENTS /* Or use INCL_GPI or INCL_PM 7 


BOOL GpiSetlnitiaiSegmentAttrs (HPS hps, LONG lAttribute, LONG IValue) 


This function specifies a segment attribute that is used when a segment is subsequently created. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

lAttribute (LONG) - input 
Segment attribute: 

ATTR_DETECT ABLE Detectability. 


This can be used to determine whether a correlation function can 
be performed on the primitives within the segment. For 
correlation on retained segments see: 

• GpiCorrelateChain 

• GpiCorrelateFrom 

• GpiCorrelateSegment. 

Correlation on primitives outside segments is controlled by the 
correlate flag on draw controls (see GpiSetDrawControl). 

ATTR_VISIBLE Visibility. 

Controls whether a segment is to be made visible on the output 
medium. 


ATTR_CHAINED 


ATTR_DYNAMIC 


ATTR_FASTCHAIN 


Chained. 

Controls whether the segment is a root segment to be included in 
the segment drawing chain. In draw or draw-and-retain modes 
(see GpiSetDrawingMode) a chained segment is drawn as it 
passes across the API; an unchained segment is not. 

Unchained segments are usually called from another segment. 
They can also be segments that are inserted into the chain later 
(with GpiSetSegmentPriority or GpiSetSegmentAttrs), or segments 
that are drawn individually with GpiDrawSegment. 

Dynamic. 

Controls whether the segment is to be dynamic; that is. drawn 
using exclusive-OR, so that it can be readily erased by redrawing 
it. (See GpiDrawDynamics, GpiRemoveDynamics, and the 
DCTL_DYNAMIC option of GpiSetDrawControl.) 

Only retained segments can be dynamic. 

The dynamic segment attribute is always ignored if the segment is 
not currently chained. 

Fast chaining. 

Controls whether, for a chained segment, the system can assume 
that all primitive attributes need not be reset to default values 
before execution of the segment. 
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GpiSetlnitialSegmentAttrs - 
Set Initial Segment Attributes 


ATTR_PROP_DETECT ABLE Propagate detectability. 

Controls whether the value of the detectability attribute for a 
segment should be propagated (forced) to all segments beneath it 
in the hierarchy. 

ATTR_PROP_ VISIBLE Propagate visibility. 

Controls whether the value of the visibility attribute for a segment 
should be propagated (forced) to all segments beneath it in the 
hierarchy. 

IValue (LONG) - input 
Attribute value: 

ATTR_ON On/yes 

ATTR_OFF Off/no. 

Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRJNVHPS 
PMERRPSBUSY 

PMERR_INV_SEG_ATTR 


PMERR_INV_SEG_ATTR_VALUE 

PMERR_INV_MICROPS_FUNCTION 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid attribute parameter was specified with 
GpiSetSegmentAttrs, GpiQuerySegmentAttrs, 
GpiSetlnitialSegmentAttrs, or 
GpiQuerylnitialSegmentAttrs. 

An invalid attribute value parameter was specified with 
GpiSetSegmentAttrs or GpiSetlnitialSegmentAttrs. 

An attempt was made to issue a function that is invalid in 
a micro presentation space. 


Remarks 

Initial segment attributes are modal settings used to determine the initial attributes of new segments 
as they are created; that is, when an GpiOpenSegment function is issued, and the segment does not 
already exist. The default values of initial segment attributes are: 

• Not detectable 

• Visible 

• Chained 

• Not dynamic 

• Fast chaining 

• Propagate detectability 

• Propagate visibility. 

A nonretained segment can never be given the dynamic attribute. 

Primitives outside segments are not affected by GpiSetlnitialSegmentAttrs. 


Chapter 5. Graphics Functions 


5-489 



GpiSetlnitialSegmentAttrs - 
Set Initial Segment Attributes 


Related Functions 

• GpiCallSegmentMatrix 

• GpiCloseSegment 

• GpiCorrelateSegment 

• GpiDeleteSegment 

• GpiDeleteSegments 

• GpiDrawSegment 

• GpiErrorSegmentData 

• GpiDrawSegment 

• GpiQuerylnitialSegmentAttrs 

• GpiSetSegmentAttrs 

• GpiSetSegmentPriority 

Example Code 

This function specifies a segment attribute that is used when a segment is subsequently created. In 
this example, the most common attributes are selected. 

Idefine INCL_GPISEGMENTS 
linclude <0S2.H> 

HPS hps; /* Presentation-space */ 

/* handle. */ 


GpiSetlnitialSegmentAttrs (hps, 

ATTR_DETECTABLE | 
ATTR_VISIBLE | 
ATTR_DYNAMIC | 
ATTR_PROP_DETECTABLE | 
ATTR_PROP_VISIBLE, 
ATTR_0N) ; 
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GpiSetLineEnd - 
Set Line End 


#define INCL_GPIPRIMITIVES /* Or use INCL_GP! or INCL_PM */ 


BOOL GpiSetLineEnd (HPS hps, LONG ILIneEnd) 


This function sets the current line-end attribute. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

ILIneEnd (LONG) - input 
Style of line end: 

Flat Square Round 



0 Geometric point of line end 
Outline of end shape 


LINEEND_DEFAULT Use default, same as LINEEND_FLAT (unless changed with 
GpiSetDefAttrs) 


LINEENDFLAT Flat 

LINEENDSQUARE Square 
LINEEND_ROUND Round. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid line end attribute value was specified. 


Possible returns from WinGetLastError 

PMERRJNVHPS 

PMERR_PS_BUSY 

PMERR_INV_LINE_END_ATTR 


Chapter 5. Graphics Functions 5-491 







GpiSetLineEnd 
Set Line End 


Remarks 

The line-end attribute defines the shape of the ends of lines or arcs at the beginning and end of an 
open figure. This attribute is used only in the GpiModifyPath function (with a I Mode parameter of 
MPATH_STROKE) or in the GpiStrokePath function. 

The attribute mode (see GpiSetAttrMode) determines whether the current value of the line-end 
attribute is preserved. 


Related Functions 

• GpiLine 

• GpiPolyLine 

• GpiQueryLineEnd 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiSetLineJoin 

• GpiSetLineType 

• GpiSetLineWidth 

• GpiSetLineWidthGeom 

Graphic Elements and Orders 

Element Type: OCODE_GSLE 

This element type is generated if the attribute mode (see GpiSetAttrMode) is set to 
AM_NOPRESERVE. 

Order: Set Line End 

Element Type: OCODE_GPSLE 

This element type is generated if the attribute mode is set to AM_PRESERVE. 
Order: Push and Set Line End 

Example Code 

This function sets the line end to be square (as opposed to round for example). 

Idefine INCL_GPIPRIMITIVES 
linclude <0S2.H> 

HPS hps ; /* Presentation-space */ 

/* handle. */ 

GpiSetLineEnd (hps, 

LINEENDSQUARE) ; 
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GpiSetLineJoin - 
Set Line Join 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetLineJoin (HPS hps, LONG ILineJoln) 


This function sets the current line-join attribute. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

ILineJoin (LONG) - input 
Style of line join: 


Bevel Round Miter 



(g) Geometric point of line join 
Outline of join shape 


LINEJOIN_DEFAULT 

LINEJOINBEVEL 

LINEJOINROUND 

LINEJOINMITRE 


Use default, same as LINEJOIN_BEVEL (unless changed with 
GpiSetDefAttrs) 

Bevel 

Round 

Miter. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid line join attribute value was specified. 


Possible returns from WinGetLastError 

PMERR_INV_HPS 

PMERR_PS_BUSY 

PMERRJNV_LlNE_JOIN_ATTR 
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GpiSetLineJoin 
Set Line Join 


Remarks 

The line-join attribute defines how individual lines and arcs within a figure are joined together. This 
attribute is used only during a GpiModifyPath function (with a /Mode parameter of MPATH_STROKE) 
or a GpiStrokePath function. 

For LINEJOIN_MITRE, where the lines going into a join are nearly parallel (a very sharp change in 
direction), a miter join could potentially extend to a distance that approaches infinity. T o prevent 
this, whenever the ratio of the miter length to the geometric line width exceeds 10, a bevel join is 
drawn instead. (The miter length is the distance from the point at which the inner edges of the 
wideline intersect, to the point at which the outer edges of the wideline intersect.) 

The attribute mode (see GpiSetAttrMode) determines whether the current value of the line-join 
attribute is preserved. 


Related Functions 

• GpiLine 

• GpiPolyLine 

• GpiQueryLineEnd 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiSetLineEnd 

• GpiSetLineType 

• GpiSetLineWidth 

• GpiSetLineWidthGeom 

Graphic Elements and Orders 

Element Type: OCODE_GSLJ 

This element type is generated if the attribute mode (see GpiSetAttrMode) is set to 
AM_NOPRESERVE. 

Order: Set Line Join 

Element Type: OCODE_GPSLJ 

This element type is generated if the attribute mode is set to AM PRESERVE. 
Order: Push and Set Line Join 

Example Code 

This function sets the line-join to be round (as opposed to bevel or miter). 

Idefine INCL_GPI PRIMITIVES 
linclude <0S2.H> 

HPS hps; /* Presentation-space */ 

/* handle. */ 

GpiSetLineEnd(hps, 

LINEJ0IN_R0UND) ; 
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GpiSetLineType - 
Set Line Type 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetLineType (HPS hps, LONG ILineType) 


This function sets the current cosmetic line-type attribute. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

ILineType (LONG) - input 
Line types available: 


LINETYPEJ3EFAULT 

LINETYPE_DOT 

LINETYPE_SHORTDASH 

LIN ETYPE_DASH DOT 

LINETYPE-DOUBLEDOT 

LINETYPEJ.ONGDASH 

LINETYPE_DASHDOUBLEDOT - 

LINETYPE_SOLID 

LINETYPE_ALTERNATE 

LINETYPEJNVISIBLE 


Solid line (the default) 
Dotted line 
Short-dashed line 
Dash-dot line 
Double-dotted line 
Long-dashed line 
Dash-double-dot line 
Solid line 
Alternate pels on 
Invisible line 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 

PMERR INV HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_LINE_TYPE_ATTR An invalid line type attribute value was specified or the 

default value was explicitly specified with GpiSetAttrs 
instead of using the defaults mask. 


Remarks 

A nonsolid line type consists of a sequence of “on” and “off” runs of pels that gives the appearance 
of a dotted or a dashed line, for example. 

This attribute specifies the cosmetic line type, which is used for all line and curve drawing. It does 
not depend upon transforms, so that, for example, dashes do not become longer when a “zoom in" 
occurs. 
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GpiSetLineType 
Set Line Type 


The standard line types are implemented on each device to give a good appearance on that device, 
taking into account the pel resolution. Their definitions cannot be changed by applications, nor may 
applications define additional cosmetic line types. 

The system maintains position within the line-type definition so that, for example, a curve may be 
implemented as a polyline. However, some functions cause position to be reset to the start of the 
definition. These are: 

• GpiCallSegmentMatrix 

• GpiMove 

• GpiPop (or end of called segment) that pops current position or a model transform 

• GpiSetCurrentPosition 

• GpiSetLineType 

• GpiSetModelTransformMatrix 

• GpiSetPageViewport 

• GpiSetSegmentTransformMatrix. 

The default line-type is solid. This can be changed with GpiSetDefAttrs. 

The attribute mode (see GpiSetAttrMode) determines whether the current value of the line-type 
attribute is preserved. 


Related Functions 

• GpiBox 

• GpiLine 

• GpiPolyLine 

• GpiQueryLineEnd 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiSetLineEnd 

• GpiSetLineJoin 

• GpiSetLineWidth 

• GpiSetLineWidthGeom 

Graphic Elements and Orders 

Element Type: OCODE_GSLT 

This element type is generated if the attribute mode (see GpiSetAttrMode) is set to 
AM_NOPRESERVE. 

Order: Set Line Type 

Element Type: OCODE_GPSLT 

This element type is generated if the attribute mode is set to AM PRESERVE. 
Order: Push and Set Line Type 
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GpiSetLineType - 
Set Line Type 


Example Code 

This function sets the line-type to be round (as opposed to bevel or miter). 

Idefine INCL_GPIPRIMITIVES 
linclude <0S2.H> 

HPS hps; /* Presentation-space */ 

/* handle. */ 


GpiSetLineType(hps, 

LINETYPE_DEFAULT) ; 
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GpiSetLineWidth 
Set Line Width 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetLineWidth (HPS hps, FIXED fxLineWidth) 


This function sets the current cosmetic line-width attribute. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

fxLineWidth (FIXED) - input 
Line-width multiplier 

LINEWIDTH_DEFAULT Use default; same as LINEWIDTH_NORMAL (unless changed with 
GpiSetDefAttrs). 

LINEWIDTH NORMAL Normal width (1.0). 

Any other positive value is a multiplier on the “normal” line width. 

LINEWIDTH_THICK Thick. 

Where only two line thicknesses, “normal” and “thick,” are supported, 
“normal" will be used for values less than or equal to 1.0 (other than 
LINEWIDTH_DEFAULT), and “thick” otherwise. 

See DevQueryCaps (CAPS_ADDITIONAL_GRAPHICS and 
CAPS_LINEWIDTH_THICK). 

Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 


P M E R R _IN VHPS 
PMERRPSBUSY 

PMERRJNV_LINE_WIDTH_ATTR 

PMERR_UNSUPPORTED_ATTR_VALUE 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid line width attribute value was specified or the 
default value was explicitly specified with GpiSetAttrs 
instead of using the defaults mask. 

An attribute value was specified with GpiSetAttrs that is 
not supported. 


Remarks 

The cosmetic line width specifies a multiplier on the “normal” line thickness for the device. 
Cosmetic thickness does not depend upon transforms, so that, for example, lines do not become 
thicker when a “zoom-in” occurs. 

The attribute mode (see GpiSetAttrMode) determines whether the current value of the line-width 
attribute is preserved. 
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GpiSetLineWidth - 
Set Line Width 


Related Functions 

• GpiBox 

• GpiLine 

• GpiPolyLine 

• GpiQueryLineEnd 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiSetLineEnd 

• GpiSetLineJoin 

• GpiSetLineType 

• GpiSetLineWidthGeom 

Graphic Elements and Orders 

Element Type: OCODE_GSFLW 

This element type is generated if the attribute mode (see GpiSetAttrMode) is set to 
AM_NOPRESERVE. 

Order: Set Fractional Line Width 

Element Type: OCODE_GPSFLW 

This element type is generated if the attribute mode is set to AM_PRESERVE. 
Order: Push and Set Fractional Line Width 

Example Code 

This function sets the line width to the default, so that there is no multiplying factor. 

Idefine INCL_GPIPRIMITIVES 
linclude <0S2.H> 

HPS hps; /* Presentation-space */ 

/* handle. */ 

GpiSetLineWidth(hps, 

LINEWIDTH_NORMAL) ; 
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GpiSetLineWidthGeom 
Set Line Width Geom 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetLineWidthGeom (HPS hps, LONG ILineWidth) 


This function sets the current geometric line-width attribute. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

ILineWidth (LONG) - input 
Geometric line width. 

The geometric line width in world coordinates. It must not be negative. 

A thickness of 0 results in an area of 0 width. Because filling includes the boundaries, this 
results in the thinnest possible lines and arcs, regardless of what transforms are in force. 

The initial default value of the geometric line width is 1. This can be changed with 
GpiSetDefAttrs. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRINVHPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_GEOM_LINE_WIDTH_ATTR An invalid geometric line width attribute value was 

specified. 

Remarks 

The geometric line-width attribute is used only in the GpiModifyPath function (with a /Mode of 
MPATH_STROKE) or in the GpiStrokePath function. This attribute specifies the width to be used in 
converting the lines and arcs, of which the path is composed, into wide lines and arcs. The resulting 
shape is treated like an area, so the boundaries are considered to be part of its interior. This means 
that the width of the lines and arcs is one pel wider than the geometric line width transformed to 
device coordinates. 

The geometric line width is specified in world-coordinate units, so that, for example, the thickness 
varies on a zoom operation. 

Normal line and curve drawing uses only the cosmetic line width (see GpiSetLineWidth). 

This function must not be issued within an area or path bracket. 

The attribute mode (see GpiSetAttrMode) determines whether the current value of the geometric line 
width is preserved. 
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GpiSetLineWidthGeom - 
Set Line Width Geom 


Related Functions 

• GpiLine 

• GpiPolyLine 

• GpiQueryLineEnd 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiSetLineEnd 

• GpiSetLineJoin 

• GpiSetLineType 

• GpiSetLineWidth 

• GpiBeginPath 

• GpiCloseFigure 

• GpiEndPath 

• GpiFil IPath 

• GpiModifyPath 

• GpiOutlinePath 

• GpiPathToRegion 

• GpiSetClipPath 

• GpiStrokePath 

Graphic Elements and Orders 

Element Type: OCODE_GSSLW 

This element type Is generated if the attribute mode (see GpiSetAttrMode) is set to 
AM_NOPRESERVE. 

Order: Set Stroke Line Width 

Element Type: OCODE_GPSSLW 

This element type is generated if the attribute mode is set to AM_PRESERVE. 
Order: Push and Set Stroke Line Width 

Example Code 

This function sets the line width geometry to double the default of 1 . 

Idefine INCL_GPIPRIMITIVES 
linclude <0S2.H> 

HPS hps; /* Presentation-space */ 

/* handle. */ 

Gpi SetLi neWi dthGeom(hps , 

2L); 
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GpiSetMarker 
Set Marker 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetMarker (HPS hps, LONG ISymbol) 


This function sets the value of the marker-symbol attribute. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

ISymbol (LONG) - input 
Marker symbol. 

The identity of the required marker symbol. Zero selects the default marker symbol, a value in 
the range 1 through 255 identifies a symbol in the current marker set. Valid values in the default 
marker set are shown below, these symbols are not necessarily available with other marker 
sets: 


MARKSYK/LDEFAULT 

MARKSYM_CROSS 

MARKSYM_PLUS 

MARKSYIVLDIAMOND 

MARKSYM_SQUARE 

MARKSYMJSIXPOINTSTAR 

MAR KSYIVLEI GHTPOI NTSTAR 

MARKSYM_SOLIDDIAMOND 

MARKSYMJSOLIDSQUARE 

MARKSYMJJOT 

MARKSYIVLSMALLCIRCLE 

M AR KSYM_B LAN K 


The default; same as MARKSYM_CROSS 
X 

+ 

O 

□ 

* 

* 

♦ 

■ 

o 

(blank) 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 

PMERRJNVHPS 

PMERRPSBUSY 

PMERRINVMARKERSYMBOLATTR 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid marker symbol attribute value was specified or 
the default value was explicitly specified with GpiSetAttrs 
instead of using the defaults mask. 
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GpiSetMarker - 
Set Marker 


Remarks 

This function must not be issued in an area bracket. 

The default marker-symbol is a cross. This can be changed with GpiSetDefAttrs. 

The attribute mode (see GpiSetAttrMode) determines whether the current value of the marker 
attribute is to be preserved. 


Related Functions 

• GpiMarker 

• GpiPolyMarker 

• GpiQueryMarker 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiSetBackColor 

• GpiSetBackMix 

• GpiSetColor 

• GpiSetMarkerBox 

• GpiSetMarkerSet 

• GpiSetMix 

Graphic Elements and Orders 

Element Type: OCODE_GSMT 

This element type is generated if the attribute mode (see GpiSetAttrMode) is set to 
AM_NOPRESERVE. 

Order: Set Marker Symbol 

Element Type: OCODE_GPSMT 

This element type is generated if the attribute mode is set to AM_PRESERVE. 
Order: Push and Set Marker Symbol 

Example Code 

This function changes the marker from the default (a cross) to a diamond. 

Idefine INCL_GPIPRIMITIVES 
linclude <0S2.H> 

HPS hps; /* Presentation-space */ 

/* handle. */ 


GpiSetMarker (hps, 

MARKSYM_DIAMOND) ; 
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GpiSetMarkerBox 
Set Marker Box 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM 7 


BOOL GpiSetMarkerBox (HPS hps, PSIZEF psIzfxSIze) 


This function sets the current marker-box attribute. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

psIzfxSIze (PSIZEF) - input 
Size of marker box. 

The size is specified in world coordinates. The fractional part of the value should be 0. 

Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERR INV HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

Remarks 

The value of the marker-box attribute affects the size of markers that are selected from a vector font 
only. The size of markers that are selected from an image font is not affected by this attribute. 

For default markers, this attribute only has an effect if the device supports the scaling of default 
markers, that is, the CAPS_SCALED_DEFAULT_MARKERS parameter in the 
CAPS_ADDITIONAL_GRAPHICS element of the device capabilities array returned by the 
DevQueryCaps function is set to 1. 

This function must not be issued in an area bracket. 

The attribute mode (see GpiSetAttrMode) determines whether the current value of the marker-box 
attribute is preserved. 

The initial default value of the marker box is the size returned by DevQueryCaps 
(CAPS_MARKER_WIDTH and CAPS_MARKER_HEIGHT), for the currently associated device, 
converted to presentation page space. 

The default value can be changed with GpiSetDefAttrs. 
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GpiSetMarkerBox - 
Set Marker Box 


Related Functions 

• DevQueryCaps 

• GpiMarker 

• GpiPolyMarker 

• GpiQueryMarkerBox 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetBackColor 

• GpiSetBackMix 

• GpiSetColor 

• GpiSetDefAttrs 

• GpiSetMarker 

• GpiSetMarkerSet 

• GpiSetMix 

Graphic Elements and Orders 

Element Type: OCODE_GSMC 

This element type is generated if the attribute mode (see GpiSetAttrMode) is set to 
AM_NOPRESERVE. 

Order: Set Marker Cell 

Element Type: OCODE_GPSMC 

This element type is generated if the attribute mode is set to AMPRESERVE. 
Order: Push and Set Marker Cell 

Example Code 

This function sets the marker box to 10 by 10. 

Idefine INCL_GPIPRIMITIVES 
linclude <0S2.H> 

HPS hps; /* Presentation-space */ 

/* handle. */ 

SIZEF fxSize = {MAKEFIXED(IO.O) , 

MAKEFIXED(10,0)}; 

/* The size is specified in */ 

/* world coordinates. The */ 

/* fractional part of the */ 

/* value should be zero. */ 

Gpi SetMar kerBox ( hps , 

&fxSize) ; 
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GpiSetMarkerSet 
Set Marker Set 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetMarkerSet (HPS hps, LONG ISet) 


This function sets the current marker-set attribute. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

ISet (LONG) - input 

Marker-set local identifier. 

The identity (Icid) of the required marker set: 

LCID_DEFAULT Default (can be set explicitly with GpiSetDefAttrs) 

1-254 Identifies a logical font. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 


PMERRJNVHPS 


An invalid presentation-space handle was specified. 


PMERR_PS_BUSY 


An attempt was made to access the presentation space 
from more than one thread simultaneously. 


PMERR_INV_MARKER_SET_ATTR An invalid marker set attribute value was specified or the 

default value was explicitly specified with GpiSetAttrs 
instead of using the defaults mask. 

PMERR_HUGE_FONTS_NOT_SUPPORTED An attempt was made using GpiSetCharSet, 

GpiSetPatternSet, GpiSetMarkerSet, or GpiSetAttrs to 
select a font that is larger than the maximum size (64Kb) 
supported by the target device driver. 


Remarks 

This function must not be issued in an area bracket. 

The attribute mode (see GpiSetAttrMode) determines whether the current value of the marker-set 
attribute is preserved. 

If the default marker set is changed (using GpiSetDefAttrs) the initial default marker set cannot be 
selected with GpiSetMarkerSet. 
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GpiSetMarkerSet - 
Set Marker Set 


Related Functions 

• GpiMarker 

• GpiPolyMarker 

• GpiQueryMarkerSet 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiSetMarker 

• GpiSetMarkerBox 

Graphic Elements and Orders 

Element Type: OCODE_GSMS 

This element type is generated if the attribute mode (see GpiSetAttrMode) is set to 
AM_NOPRESERVE. 

Order: Set Marker Set 

Element Type: OCODE_GPSMS 

This element type is generated if the attribute mode is set to AMPRESERVE. 
Order: Push and Set Marker Set 

Example Code 

This function changes the marker set to one defined by the logical font with id 26. 

Idefine INCL_GPIPRIMITIVES 
#include <0S2.H> 

HPS hps; /* Presentation-space */ 

/* handle. */ 

Gpi SetMarkerSet ( hps , 

26L); 
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GpiSetMetaFileBits 
Set Metafile Bits 


#define INCL_GPIMETAFILES /* Or use INCL_GPI or INCL_PM 7 


BOOL GpiSetMetaFileBits (HMF hmf, LONG lOffset, LONG ILength, PBYTE pbBuffer) 


This call transfers metafile data from application storage into a memory metafile. 

Parameters 

hmf (HMF) - input 

Metafile-memory handle. 

lOffset (LONG) - input 
Offset. 

Offset, in bytes, into the metafile data from where the transfer must start. This is used when the 
metafile data is too long to fit into a single application buffer. 

ILength (LONG) - input 

Length of the metafile data. 

pbBuffer (PBYTE) - input 
Metafile data buffer. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 


PMERRJNVHMF 

PMERR _INV_MET AFILELENGTH 

PMERR_INV_M ET AFILEOFFSET 

PMERRMET AFILE _IN_USE 


An invalid metafile handle was specified. 

An invalid length parameter was specified with 
GpiSetMetaFileBits or GpiQueryMetaFileBits. 

An invalid length parameter was specified with 
GpiSetMetaFileBits or GpiQueryMetaFileBits. 

An attempt has been made to access a metafile that is in 
use by another thread. 


Remarks 

The application must ensure that the data is in the correct format. It should not have been changed 
since it was created by GpiQueryMetaFileBits. 

The length of the metafile is increased, if necessary, to accommodate the supplied data. If the 
supplied data is shorter, the metafile length is not reduced. However, in this case the metafile is still 
valid, if the data in it is complete and otherwise correct. 
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GpiSetMetaFileBits - 
Set Metafile Bits 


Related Functions 

• GpiCopyMetaFile 

• GpiDeleteMetaFile 

• GpiLoadMetaFile 

• GpiPlayMetaFile 

• GpiQueryMetaFileBits 

• GpiQueryMetaFileLength 

• GpiSaveMetaFile 

Example Code 

This example shows how to copy a metafile into application storage to edit the contents and then 
write back to the metafile using the GpiSetMetaFileBits call. 

Idefine INCL_GPIMETAFILES 
finclude <0S2.H> 

HPS hps; /* 

/* 

HMF hmf; 

PBYTE pbBuffer; 

LONG cBytes; 

LONG 1 Offset; 

hmf = GpiLoadMetaFile (hps, "sample. met") ; 

/* Allocate the buffer for the metafile data. */ 

cBytes = GpiQueryMetaFileLength (hmf);/* gets length of metafile */ 

DosAllocMem((PPVOID)pbBuffer, 
cBytes, 

PAG_READ | 

PAG_WRITE | 

PAG_COMMIT) ; 

Gpi QueryMetaFi 1 eBi ts ( 
hmf, 

1 Offset, 
cBytes, 
pbBuffer) ; 

/* • */ 

/* work with the metafile */ 

/* • */ 

/* write data back to the metafile */ 

Gpi SetMetaFi 1 eBi ts (hmf , 

1 Offset, 
cBytes, 
pbBuffer) ; 


/* handle of metafile */ 
/* offset of next byte to retrieve */ 
/* retrieves cBytes */ 
/* buffer to receive metafile data */ 


Presentation-space */ 
handle. */ 
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GpiSetMix 
Set Mix 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetMix (HPS hps, LONG IMIxMode) 


This function sets the current foreground mix attribute for each individual primitive type. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

IMIxMode (LONG) - input 
Mix mode. 

Defines the color-mixing mode. 

Mixing other than FMLEAVEALONE or FMOVERPAINT is done on the physical color index. In 
general, this corresponds to the color index of the logical color table if an indexed color table 
has been realized. In other circumstances, the color that results from such a mix cannot be 
predicted. Nevertheless, if FM_XOR is supported for example, drawing the same object twice 
with a foreground mix of FM_XOR and a background mix of BM_LEAVEALONE with no 
intervening drawing in other mix modes, causes the object to be erased cleanly. 

The currently associated device supports any of the mixes specified as supported in 
DevQueryCaps (CAPS_FOREGROUND_MIX_SUPPORT). Any other valid mixes may be supported 
for some primitive types, but otherwise results in FM_OVERPAINT. An error is raised only if the 
value specified is not one of those listed below. 

Note: Mixes marked with an asterisk (*) are mandatory for all devices, except that FMOR is 
only mandatory for devices capable of supporting it. FM_XOR is mandatory only on 
displays. 


FM_DEFAULT 

Use default, the same as FM OVERPAINT, unless changed with 
GpiSetDefAttrs 

FM_OR 

Logical-OR (*) 

FMOVERPAINT 

Overpaint (*) 

FM_XOR 

Logical-XOR (*) 

FMLEAVEALONE 

Leave alone (invisible) (*) 

FM_AND 

Logical-AND 

FMSUBTRACT 

(Inverse source) AND destination 

FMMASKSRCNOT 

Source AND (inverse destination) 

FM ZERO 

All zeros 

FM_NOTMERGESRC 

Inverse (source OR destination) 

FMNOTXORSRC 

Inverse (source XOR destination) 

FMJNVERT 

Inverse (destination) 

FMMERGESRCNOT 

Source OR (inverse destination) 

FM_NOTCOPYSRC 

Inverse (source) 

FMMERGENOTSRC 

(Inverse source) OR destination 

FMNOTMASKSRC 

Inverse (source AND destination) 

FM ONE 

All ones. 
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GpiSetMix - 
Set Mix 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRJNV_HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_MIX_ATTR An invalid mix attribute value was specified or the default 

value was explicitly specified with GpiSetAttrs instead of 
using the defaults mask. 

Remarks 

The current values for each primitive type are updated. The attribute mode (see GpiSetAttrMode) 
determines whether the current value of the mix attribute is preserved. 

Note: There are restrictions on the use of this function when creating SAA-conforming metafiles; 
see “Metafile Restrictions” on page G-1. 

Related Functions 

• DevQueryCaps 

• GpiBeginArea 

• GpiBox 

• GpiCharString 

• GpiCharStringAt 

• GpiCharStringPos 

• GpiCharStringPosAt 

• GpiEndArea 

• GpiFullArc 

• GpiLine 

• GpiMarker 

• GpiMove 

• GpiPartialArc 

• GpiPointArc 

• GpiPolyFillet 

• GpiPolyFilletSharp 

• GpiPolyLine 

• GpiPolyMarker 

• GpiPolySpline 

• GpiQueryCharStringPos 

• GpiQueryCharStringPosAt 

• GpiQueryMix 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetBackColor 

• GpiSetBackMix 

• GpiSetColor 

• GpiSetDefAttrs 

• WinSetSysColors 
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GpiSetMix 
Set Mix 


Graphic Elements and Orders 

Element Type: OCODE_GSMX 

This element type is generated if the attribute mode (see GpiSetAttrMode) is set to 
AM_NOPRESERVE. 

Order: Set Mix 

Element Type: OCODE_GPSMX 

This element type is generated if the attribute mode is set to AM_PRESERVE. 

Order: Push and Set Mix 

Example Code 

This function sets the current foreground mix attribute for each individual primitive type. 

Idefine INCL_GPIPRIMITIVES 
linclude <0S2.H> 

HPS hps; /* Presentation-space */ 

/* handle. */ 


GpiSetMix(hps, 

FM_LEAVEALONE) ; 
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GpiSetModelTransformMatrix - 
Set Model Transform Matrix 


#define INCL_GPITRANSFORMS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetModelTransformMatrix (HPS hps, LONG ICount, PMATRIXLF pmatlfArray, 

LONG lOptions) 


This function sets the model transform matrix for subsequent primitives. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

ICount (LONG) - input 

Number of elements in matrix. 

The number of elements of pmatlfArray to be examined, starting from the beginning of the 
structure. If ICount is less than 9, remaining elements default to the corresponding elements of 
the identity matrix. If ICount = 0 , the identity matrix is used. 

pmatlfArray (PMATRIXLF) - input 
Transformation matrix. 


The elements of the transform, in row order. The first, second, fourth, and fifth elements are of 
type FIXED, and have an assumed binary point between the second and third bytes. Thus a 
value of 1.0 is represented by 65 536. Other elements are normal signed integers. If the 
presentation space coordinate format is GPIF SHORT (see GpiCreatePS), these elements must 
be within the range —1 through +1. 

The third, sixth, and ninth elements, when specified, must be 0, 0, and 1, respectively. 

lOptions (LONG) - input 
Transform options. 

Specifies how the transform defined by the pmatlfArray should be used to modify the existing 
current model transform (the existing transform is the concatenation, in the current call context, 
of the instance, segment and model transforms, from the root segment downwards). Possible 
values are: 


TRANSFORM_REPLACE The previous model transform is discarded and replaced by the 

specified transform. 


TRANSFORM_ADD The specified transform is combined with the existing model 

transform, in the order (1) existing transform, (2) new transform. This 
option is most useful for incremental updates to transforms. 

TRANSFORM_PREEMPT The specified transform is combined with the existing model 

transform, in the order (1) new transform, (2) existing transform. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERR INV HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 
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GpiSetModeiTransformMatrix - 
Set Model Transform Matrix 


PMERR_INV_LENGTH_OR_COUNT 

PMERRINVMATRIXELEMENT 

PMERRJNV_TRANSFORM_TYPE 


An invalid length or count parameter was specified. 

An invalid transformation matrix element was specified. 

An invalid options parameter was specified with a 
transform matrix function. 


Remarks 

The matrix is used to update the previous current model transform, depending upon the value of 
I Options . 

The transform is specified as a one-dimensional array of ICount elements, being the first elements of 
a 3-row by 3-column matrix ordered by rows. The order of the elements is: 

Matrix Array 


a b 0 
c d 0 
e f 1 


(a,b,0,c,d,0,e,f,l) 


The transform acts on the coordinates of the primitives in a segment, so that a point with coordinates 
(x,y) is transformed to the point: 

(a*x + c*y + e, b*x + d*y + f) 

If scaling values greater than unity are given (which only applies if the presentation space coordinate 
format as set by the GpiCreatePS function is GPIF LONG) it is possible for the combined effect of 
this, and any other relevant transforms, to exceed fixed-point implementation limits. This causes an 
error. 

The attribute mode (see GpiSetAttrMode) determines whether the current value of the model 
transform is preserved. 

Model transforms can apply to primitives either inside or outside segments. 


Related Functions 

• GpiCallSegmentMatrix 

• GpiQueryModelTransformMatrix 

• GpiQuerySegmentTransformMatrix 

• GpiSetSegmenfTransformMatrix 

Graphic Elements and Orders 

Element Type: OCODE_GSTM 

This element type is generated if the attribute mode (see GpiSetAttrMode) is set to 
AM_NOPRESERVE. 

Order: Set Model Transform 

Element Type: OCODE_GPSTM 

This element type is generated if the attribute mode is set to AM_PRESERVE. 
Order: Push and Set Model Transform 
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Set Model Transform Matrix 


Example Code 

This function sets the model transformation matrix as one which scales everything by a factor of 2. 

Idefine INCL_GPITRANSFORMS 
linclude <0S2.H> 

HPS hps; /* Presentation-space */ 

/* handle. */ 

MATRIXLF mat If = { MAKEFIXED(2,0) , /* see pmgpi.h for a */ 

/* definition of the */ 

/* MAKEFIXED macro. */ 

0 , 0 , 0 , 

MAKEFIXED(2,0), 

0, 0, 0, l}; 


Gpi SetModel T ransf ormMatr i x ( hps , 

1L, 

&matlf , 

TRANSFORM_REPLACE) ; 
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GpiSetPageViewport 
Set Page Viewport 


#define INCL_GPITRANSFORMS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetPageViewport (HPS hps, PRECTL prciVlewport) 


This function sets the page viewport within device space. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

prciViewport (PRECTL) - input 
Page viewport. 

The page viewport is specified in device units. 

Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRINVHPS 
PMERRPSBUSY 

PMERRJNVPAGEVIEWPORT 

PMERRINVCOORDINATE 

Remarks 

The presentation page maps to the page viewport and together they define the device transform. 

When a presentation space is associated with a device context, a default page viewport is set up. 

The origin in device space is mapped to the bottom-left of the output media (window or paper, for 
example). 

This function must not be issued when there is no device context associated with the presentation 
space. 

This function is ignored if issued to a presentation space that is associated with a device context of 
type OD_QUEUED (with PM_Q_STD data), OD_METAFILE, or OD_METAFILE_NOQUERY. 

Related Functions 

• GpiCreatePS 

• GpiQueryPageViewport 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid viewport parameter was specified with 
GpiSetPageViewport. 

An invalid coordinate value was specified. 
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GpiSetPageViewport - 
Set Page Viewport 


Example Code 

This example sets the area of the device in which the picture is displayed to page viewport within 
device space. 

Idefine INCL_GPITRANSFORMS 
linclude <0S2.H> 

HPS hps; /* Presentation-space */ 

/* handle. */ 

RECTL rcl Field = {25L, /* x coordinate of left-hand edge of */ 

/* rectangle. */ 

25L, /* y coordinate of bottom edge of */ 

/* rectangle. */ 

425L, /* x coordinate of right-hand edge of */ 

/* rectangle. */ 

425L}; /* y coordinate of top edge of 
/* rectangle. */ 


Gpi SetPage Vi ewport ( hps , &rcl Field); 


Chapter 5. Graphics Functions 


5-517 



GpiSetPaletteEntries 
Set Palette Entries 


#define INCL_GPILOGCOLORTABLE /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetPaletteEntries (HPAL hpal, ULONG uiFormat, ULONG uiStart, ULONG uiCount, 

PULONG aTable) 


This function changes the entries in a palette. 


Parameters 

hpal (HPAL) - input 
Palette handle. 

uiFormat (ULONG) - input 

Format of entries in the table: 

LCOLF_CONSECRGB Array of RGB values, corresponding to color indexes uiStart upwards. 
Each entry is 4 bytes long. 

This is currently the only valid value for this parameter. 

uiStart (ULONG) - input 
Starting index. 

uiCount (ULONG) - input 

Count of elements in aTable. 

This must be greater than or equal to 0. 

aTable (PULONG) - input 

Start of the application data area. 

This contains the palette definition data. The format depends on the value of uiFormat. 

Each color value is a 4-byte integer, with a value of 
(F * 16777216) + (R * 65536) + (G * 256) + B 
where: 

F is a flag byte, which can take the following values (these can beORed together if required): 
PC_RESERVED This index is an animating index. This means that the application might 

frequently change the RGB value, so the system should not map the logical 
index of the palette of another application to the entry in the physical 
palette used for this color. 

PC_EXPLICIT The low-order word of the logical color table entry designates a physical 

palette entry. This allows an application to show the contents of the device 
palette as realized for other logical palettes. This does not prevent the 
color in the entry from being changed for any reason. 

R is red intensity value 
G is green intensity value 
B is blue intensity value. 

The maximum intensity for each primary is 255. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


5-518 PM Programming Reference 







GpiSetPaletteEntries - 
Set Palette Entries 


Possible returns from WinGetLastError 


PMERRINVHPAL 
PMERR_INV_LENGTH_OR_COUNT 
P M E R R_IN V_COLOR_DAT A 

PMERR_INV_COLOR_FORMAT 

PMERR_INV_COLOR_ST ART INDEX 

PMERRINSUFFICIENTMEMORY 

PMERR_PALETTE_BUSY 

PMERRINVINAREA 


An invalid color palette handle was specified. 

An invalid length or count parameter was specified. 

Invalid color table definition data was specified with 
GpiCreateLogColorTable. 

An invalid format parameter was specified with 
GpiCreateLogColorTable. 

An invalid starting index parameter was specified with a 
logical color table or color query function. 

The operation terminated through insufficient memory. 

An attempt has been made to reset the owner of a palette 
when it was busy. 

An attempt was made to issue a function invalid inside an 
area bracket. This can be detected while the actual 
drawing mode is draw or draw-and-retaln or during 
segment drawing or correlation functions. 


Remarks 

The changes made by this function do not become apparent until WinRealizePalette is called, even 
for animating indices. Changes can be made more rapidly using GpiAnimatePalette with animating 
indices, assuming that the hardware being used supports this. 

GpiSetPaletteEntries can be called at any time to change a logical palette, and the physical palette of 
the device will incorporate the changes as best it can. However, the system cannot guarantee that a 
change will be realized in the hardware palette, since realization depends on whether the associated 
window is in the foreground and on the number of available hardware palette entries. 

All presentation spaces that have this palette selected into them (see GpiSelectPalette), are updated 
with the effects of this function. 

If a palette is selected into a presentation space that is associated with a device context of type 
OD METAFILE or OD_METAFILE_NOQUERY, only the final color values are recorded in the metafile. 
This means that, while metafiling, this function must only be used for incremental additions to the 
color table. 

It is an error if a palette is selected into a presentation space that is within an area or path definition 
when this function is issued. 

Related Functions 

• GpiAnimatePalette 

• GpiCreatePalette 

• GpiDeletePalette 

• GpiQueryPalette 

• GpiQueryPalettelnfo 

• GpiSelectPalette 

• WinRealizePalette 
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GpiSetPaletteEntries 
Set Palette Entries 


Example Code 

This example changes the entries in a palette. 

Idefine INCL_GPILOGCOLORTABLE 
linclude <0S2.H> 

HPAL hpal; /* palette handle */ 

UINT R, G, B; 
typedef struct ENTRY 
{ 

ULONG index; 

ULONG pal_def; 

}Entry; 

struct TABLE 

{ 

Entry entry 1; 

Entry entry2; 

Entry entry3; 

}Table; 

BYTE F = PC_RESERVED; 

/* In our table, there are 3 8-byte entries. The first 4 bytes */ 
/* of each entry represent the index and the second 4 bytes of */ 


/* each entry represent the value of the following formula: */ 
/* */ 
/* (F * 16777216) + (R * 65536) + (G * 256) + B */ 
/* */ 
/* which is the palette definition. */ 
/* where F is the flag PC_RESERVED and R,G,B are the red, */ 
/* green, and blue intensity values respectively. */ 


F = 10; R = 10; G = 10; 

Table. entry 1. pal _def = (F * 16777216)+(R * 65536)+(G * 256) + B; 
Table. entry 1. index = 0L; 

F = 25; R = 25; G = 25; 

Table. entry2.pal_def = (F * 16777216)+(R * 65536)+(G * 256) + B; 
Table. entry2. index = 1L; 

F = 40; R = 40; G = 40; 

Table. entry3.pal_def = (F * 16777216)+(R * 65536)+(G * 256) + B; 
Table. entry3. index = 2L; 

Gpi SetPal etteEntri es (hpal , 

LCOLF_CONSECRGB, /* Array of RGB values, */ 
/* corresponding to color */ 


/* indexes 1 Start */ 

/* upwards. Each entry */ 

/* is 4 bytes long. */ 

0L, /* start at zero. */ 

3L, /* elements in table. */ 


STabl e. entry 1. i ndex) ; /* first element in table. */ 
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GpiSetPattern - 
Set Pattern 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM. Also in COMMON section */ 


BOOL GpiSetPattern (HPS hps, LONG IPatternSymbol) 


This function sets the current value of the pattern-symbol attribute. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

IPatternSymbol (LONG) - input 
Pattern symbol. 

Identifies the shading pattern to be used to fill areas. The pattern that appears depends on the 
particular pattern set selected by the pattern-set attribute. A value of 0 selects the default 
pattern and values in the range 1 through 255 select particular patterns within the set. 

Possible values if the default pattern set has been selected are: 


Symbolic name 

Description 

Pattern number 
(see Figure 5-10) 

PATSYM_DEFAULT 

The default; same as 
PATSYM_SOLID (unless 
changed with 

GpiSetDefAttrs). 


PATSYM_DENSE1 through 
PATSYM_DENSE8 

Solid shading with 
decreasing density 

1 through 8 

PATSYM_VERT 

Vertical pattern 

9 

PATSYM_HORIZ 

Horizontal pattern 

10 

PATSYM_DIAG1 

Diagonal pattern 1, bottom 
left to top right 

11 

PATSYM_DIAG2 

Diagonal pattern 2, bottom 
left to top right 

12 

PATSYM_DIAG3 

Diagonal pattern 3, top left to 
bottom right 

13 

PATSYM_DIAG4 

Diagonal pattern 4, top left to 
bottom right 

14 

PATSYM NOSHADE 

No shading 

15 

PATSYMSOLID 

Solid shading 

16 

PATSYM HALFTONE 

Alternate pels set on 


PATSYM_BLANK 

Blank (same as 

PATSYM NOSHADE) 



Note: The pattern PATSYM_HALFTONE can be the same as PATSYM_DENSE4. On non 
bit-mapped devices it may be mapped to another base pattern. 

If the specified pattern is not valid, the default (device-dependent) pattern is used. 
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GpiSetPattern - 
Set Pattern 

Returns 

Success indicator: 

TRUE Successful completion 

FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERR_INV_HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_PATTERN_ATTR An invalid pattern symbol attribute value was specified or 

the default value was explicitly specified with GpiSetAttrs 
instead of using the defaults mask. 


Remarks 

Any symbol from a raster font can be used as a pattern by the appropriate use of this function and 
the GpiSetPatternSet function. 

If the current pattern set specifies a bit map (see GpiSetBitmapid and GpiSetPatternSet), the pattern 
attribute is ignored. 

If IPatternSymbol is set or defaulted to PATSYM_SOLID, and the ISet parameter of GpiSetPatternSet 
is LCID_DEFAULT, pattern colors that are not available may be approximated by dithering (unless 
dithering has been disabled by setting the LCOL PURECOLOR bit on the flOptions parameter of 
GpiCreateLogColorTable). 

This function must not be issued in an area or path bracket. 

The attribute mode (see GpiSetAttrMode) determines whether the current value of the pattern symbol 
is preserved. 



Figure 5-10. Shading patterns in the default pattern set 
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GpiSetPattern - 
Set Pattern 


Related Functions 

• GpiBeginArea 

• GpiEndArea 

• GpiQueryPattern 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetBackColor 

• GpiSetBackMix 

• GpiSetColor 

• GpiSetDefAttrs 

• GpiSetMix 

• GpiSetPatternRefPoint 

• GpiSetPatternSet 

Graphic Elements and Orders 

Element Type: OCODE_GSPT 

This element type is generated if the attribute mode (see GpiSetAttrMode) is set to 
AM_NOPRESERVE. 

Order: Set Pattern Symbol 

Element Type: OCODE_GPSPT 

This element type is generated if the attribute mode is set to AMPRESERVE. 

Order: Push and Set Pattern Symbol 

Example Code 

This function sets the current value of the pattern-symbol to horizontal. This means that when areas 
are filled, they are filled with a horizontal shading pattern. 

fdefine INCL_GPIPRIMITIVES 
linclude <0S2.H> 

HPS hps; /* Presentation-space */ 

/* handle. */ 

Gpi SetPattern (hps , PATSYM_HORIZ) ; 
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GpiSetPatternRefPoint - 
Set Pattern Reference Point 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetPatternRefPoint (HPS hps, PPOINTL pptiRefPoint) 


This function sets the current pattern reference point to the specified value. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

pptiRefPoint (PPOINTL) - input 
Pattern reference point. 

The coordinates are world coordinates. 

Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERR_INV_HPS 
PMERRPSBUSY 

PMERRJNVCOORDINATE 

Remarks 

The pattern reference point is the point to which the origin of the area filling pattern maps. The 
pattern is mapped into the area to be filled by conceptually replicating the pattern definition in a 
horizontal and vertical direction. 

Because the pattern reference point is subject to all of the transforms, if an area is moved by 
changing a transform and redrawing, the fill pattern also appears to move, so as to retain its position 
relative to the area boundaries. 

The pattern reference point, which is specified in world coordinates, need not be inside the actual 
area to be filled. The pattern reference point is not subject to clipping. 

This function must not be issued in an area or path bracket. 

The attribute mode (see GpiSetAttrMode) determines whether the current value of the pattern 
reference point is preserved. 

The initial default pattern reference point is (0,0). This can be changed with GpiSetDefAttrs. 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid coordinate value was specified. 
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GpiSetPattern Ref Point - 
Set Pattern Reference Point 


Related Functions 

• GpiBeginArea 

• GpiEndArea 

• GpiQueryPatternRefPoint 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiSetPattern 

• GpiSetPatternSet 

Graphic Elements and Orders 

Element Type: OCODE_GSPRP 

This element type is generated if the attribute mode (see GpiSetAttrMode) is set to 
AM_NOPRESERVE. 

Order: Set Pattern Reference Point 

Element Type: OCODE_GPSPRP 

This element type is generated if the attribute mode is set to AM PRESERVE. 
Order: Push and Set Pattern Reference Point 

Example Code 

This function sets the current pattern reference point to the specified value. 

Idefine INCL_GPIPRIMITIVES 
linclude <0S2.H> 

HPS hps; /* Presentation-space */ 

/* handle. */ 

POINTL ptl Ref Point = {0,0}; 

Gpi SetPatternRef Poi nt (hps , &ptl Ref Poi nt) ; 
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GpiSetPatternSet 
Set Pattern Set 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetPatternSet (HPS hps, LONG ISet) 


This function sets the current pattern-set attribute to the specified value. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

ISet (LONG) - input 

Pattern-set local identifier: 

LCID_DEFAULT Default (can be set explicitly with GpiSetDefAttrs). 
1 -254 Identifies a logical font or a bit map. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 


PMERRJNVHPS 

PMERR_PS_BUSY 

P M ER R_IN VP ATT ERNSETATTR 


PMERR_INV_PATTERN_SET_FONT 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid pattern set attribute value was specified or the 
default value was explicitly specified with GpiSetAttrs 
instead of using the defaults mask. 

An attempt was made to use an unsuitable font as a 
pattern set. 


PMERR_HUGE_FONTS_NOT_SUPPORTED An attempt was made using GpiSetCharSet, 

GpiSetPatternSet, GpiSetMarkerSet, or GpiSetAttrs to 
select a font that is larger than the maximum size (64Kb) 
supported by the target device driver. 


Remarks 

The bit map, or character within the font selected, is used for shading. On some devices, a simplified 
form of the bit map, or character, is used. For example, only a subset such as the first 8 by 8 pels 
may be used; also on a monochrome device a color bit map is converted to monochrome. 

Some fonts are not suitable, and an error is returned if an attempt is made to set them as the current 
pattern set. These include device fonts that cannot be used for shading, and any kind of raster font 
for a plotter device. 

This function must not be issued in an area or path bracket. 

The attribute mode (see GpiSetAttrMode) determines whether the current value of the pattern-set 
attribute is preserved. 

If the default pattern set is changed (using GpiSetDefAttrs), the initial default pattern marker set 
cannot be selected with GpiSetPatternSet. 
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GpiSetPatternSet - 
Set Pattern Set 


Related Functions 

• GpiBeginArea 

• GpiCreateLogFont 

• GpiEndArea 

• GpiQueryPatternSet 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiSetPattern 

• GpiSetPatternRefPoint 

Graphic Elements and Orders 

Element Type: OCODE_GSPS 

This element type is generated if the attribute mode (see GpiSetAttrMode) is set to 
AM_NOPRESERVE. 

Order: Set Pattern Set 

Element Type: OCODE_GPSPS 

This element type is generated if the attribute mode is set to AMPRESERVE. 
Order: Push and Set Pattern Set 

Example Code 

This function sets the current pattern-set attribute to the logical font with id 35. 

Idefine INCL_GPIPRIMITI VES 
linclude <0S2.H> 

HPS hps; /* Presentation-space */ 

/* handle. */ 


GpiSetPatternSet(hps, 35L); 
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GpiSetPel 
Set Pel 


#define INCL_GPIBITMAPS /* Or use INCL_GPI or INCL_PM */ 


LONG GpiSetPel (HPS hps, PPOINTL pptIPoint) 


This function sets a pel, at a position specified in world coordinates, using the current (line) color and 
mix. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

pptIPoint (PPOINTL) - input 

Position in world coordinates. 


Returns 

Correlation and error indicators: 

GPI_OK Successful 

GPI_HITS Correlate hits 

GPIJERROR Error. 

Possible returns from WinGetLastError 

PMERR_INV_HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_COORDINATE An invalid coordinate value was specified. 

Remarks 

This function is subject to all the usual clipping (clip path, clip region, viewing limits, graphics field, 
visible region), and no error is returned if the point is subject to clipping. 

This function is independent of drawing mode (see GpiSetDrawingMode); the effect always occurs 
immediately, and it is not retained even if the drawing mode is draw-and-retain or retain. (Its effect 
is, however, recorded in a metafile, but note that this is only successful if the metafile is replayed on 
a similar device, with draw drawing mode.) 

Note: This function must not be used when creating SAA-conforming metafiles; see “Metafile 
Restrictions" on page G-1. 

Related Functions 

• DevQueryCaps 

• GpiQueryPel 

• GpiSetAttrs 

• GpiSetBackColor 

• GpiSetBackMix 

• GpiSetColor 

• GpiSetDefAttrs 

• GpiSetMix 
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GpiSetPel - 
Set Pel 


Example Code 

This function sets a pel, at a position specified in world coordinates, using the current (line) color and 
mix. 

Idefine INCL_GPIBITMAPS 
linclude <0S2.H> 

HPS hps; /* Presentation-space */ 

/* handle. */ 


POINTL ptl Point = {0,0}; 


GpiSetPel (hps, &ptl Poi nt) ; 
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GpiSetPickAperturePosition 
Set Pick-Aperture Position 


#define INCL_GPICORRELATION /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetPickAperturePosition (HPS hps, PPOINTL pptIPIck) 


This function sets the center of the pick aperture, in presentation page space, for subsequent 
nonretained correlation operations. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

pptIPIck (PPOINTL) - input 
Center of the pick aperture. 

The center is in presentation page coordinates. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERR_INV_HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_COORDINATE An invalid coordinate value was specified. 

Related Functions 

• GpiQueryPickAperturePosition 

• GpiQueryPickApertureSize 

• GpiSetPickApertureSize 

Example Code 

In this example we query the position of the center of the pick aperture. 


fdefine INCL_GPICORELATION 
linclude <0S2.H> 

BOOL fl Result; 

HPS hps; /* Presentation space handle. */ 

POINTL ptl Point = {50L, 50L}; /* Pick-aperture position. */ 

flResult = GpiSetPickAperturePosition(hps, &ptl Poi nt ) ; 
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GpiSetPickApertureSize - 
Set Pick-Aperture Size 


#define INCLGPICORRELATION /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetPickApertureSize (HPS hps, LONG lOptlons, PSIZEL psizISize) 


This function sets the pick-aperture size. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

lOptions (LONG) - input 
Setting option: 

PICKAP_DEFAULT Use the default pick aperture. The value of psizISize is ignored. 

PICKAP_REC Use the values specified by psizISize. 

psizISize (PSIZEL) - input 
Pick aperture size. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 


PMERRJNVHPS 

PMERRPSBUSY 

PMERR_INV_PICK_APERTURE_OPTION 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid options parameter was specified with 
GpiSetPickApertureSize 


PMERR_INV_PICK_APERTURE_SIZE An invalid size parameter was specified with 

GpiSetPickApertureSize 


Remarks 

The pick aperture can be set either to the default value, or to a specified size in presentation page 
space. This is used in any subsequent nonretained or retained correlation operations. 

The default size is a rectangle in presentation page space that produces a square on the device, with 
side equal to the default character cell height. 


Related Functions 

• GpiQueryPickApertureSize 

• GpiSetPickAperturePosition 

• GpiQueryPickAperturePosition 
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GpiSetPickApertureSize 
Set Pick-Aperture Size 


Example Code 

In this example we set the pick-aperture size to a 4 by 4 box in world coordinates. 

Idefine INCL_GPICORRELATION 
linclude <0S2.H> 

HPS hps; /* Presentation space handle. */ 

SIZEL sizel; /* Pick-aperture position. */ 

sizel.cx = 4L; sizel. cy = 4L; 

GpiSetQueryPickApertureSize(hps, &sizel ) ; 
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GpiSetPS - 
Set Presentation Space 


#define INCL_GPICONTROL /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetPS (HPS hps, PSIZEL pslzlslze, ULONG flOptions) 


This function sets the presentation space size, units, and format. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

pslzlsize (PSIZEL) - input 
Presentation-space size. 

flOptions (ULONG) - input 
Options. 


This contains fields of option bits. For each field, one value should be selected (unless the 
default is suitable). These values can then be ORed together to generate the parameter. 


PSUNITS 

Presentation page size units. 

Indicates the units for the presentation page size. In each case, the origin is at the bottom 
left. Possible values are: 


PU_ARBITRARY 
PUPELS 
PULOMETRIC 
PUHIMETRIC 
PULOENGLISH 
PUHIENGLISH 
PUTWIPS 

PS_FORMAT 

Coordinate format. 


Application-convenient units 

Pel coordinates 

Units of 0.1 mm 

Units of 0.01 mm 

Units of 0.01 inch 

Units of 0.001 inch 

Units of 1/1440 inch. 


Indicates options to be used when storing coordinate values internally in the segment store. 

For most calls, the format is not directly visible to an application. However, it is visible 
during editing (for example, GpiQueryElement). The format also has an effect on the 
amount of storage required for segment store. 

One of these can be selected, for a GPIT_NORMAL presentation space (for a GPITMICRO 
presentation space, only GPIF_DEFAULT is allowed): 

GPIF_DEFAULT Default local format (same as GPIF_LONG) 

GPIF_SHORT 2-byte integers 

GPIF LONG 4-byte integers. 

PSTYPE 

Presentation space. 

This option is ignored. 


PS_MODE 

Mode. 

This option is ignored. 
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GpiSetPS - 

Set Presentation Space 


PS_ASSOCIATE 

Association indicator. 

This option is ignored. 

PS_NORESET 

Inhibit full reset indicator. 


Inhibits the full reset of the presentation space. If this flag is set, a reset equivalent to 
GRES_SEGMENTS is performed. If it is not set, a full reset (GRES_ALL) is performed. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 


PMERRINVHPS 

PMERR_PS_BUSY 

PMERRINVHDC 

P M E R R_IN V_PS_SIZE 

PMERRJNVORJNCOMPATOPTIONS 

PMERR_INV_FOR_THIS_DC_TYPE 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid device-context handle or (micro presentation 
space) presentation-space handle was specified. 

An invalid size parameter was specified with 
GpiCreatePS or GpiSetPS. 

An invalid or incompatible (with micro presentation 
space) options parameter was specified with 
GpiCreatePS or GpiSetPS. 

An attempt has been made to issue GpiRemoveDynamics 
or GpiDrawDynamics to a presentation space associated 
with a metafile device context. 


Remarks 

The presentation space is re-initialized to the same state that occurs as if it had been created using 
the specified size and option values. However, whether the presentation space is a micro 
presentation space or a normal presentation space cannot be changed, and any device context that 
is already associated remains associated. 

The presentation space code page is set to the current process code page. 

On completion, the presentation space is reset with the equivalent of GRES_ALL (see GpiResetPS), 
unless PS_NORESET is specified, in which case only the equivalent of a GRES_SEGMENTS reset is 
performed. 

This function cannot be used to a presentation space that is associated with a device context of type 
OD_QUEUED, OD_METAFILE, or OD_METAFILE_NOQUERY. 

Related Functions 

• GpiAssociate 

• GpiCreatePS 

• GpiDestroyPS 

• GpiQueryDevice 

• GpiQueryPS 

• GpiResetPS 

• GpiRestorePS 

• GpiSavePS 
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GpiSetPS - 
Set Presentation Space 


Example Code 

This function is used to reset the presentation space. 

linclude <0S2.H> 

Idefine INCL_GPICONTROL 

HPS hps; /* presentation space handle */ 

ULONG fl Options; /* reset options */ 

fl Options = PU_ARBITRARY | /* arbitrary units. */ 

GPIF_DEFAULT j /* normal ps format. */ 

GpiSetPS(hps, flOptions); 
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GpiSetRegion 
Set Region 


#define INCL_GPIREGIONS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetRegion (HPS hps, HRGN hrgn, LONG Icount, PRECTL arciRectangles) 


This function changes a region to be the logical-OR of a set of rectangles. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

The region must be owned by the device identified by the currently associated device context. 

hrgn (HRGN) - input 
Region handle. 

Icount (LONG) - input 
Count of rectangles. 

This is the number of rectangles specified in arciRectangles. If Icount = 0, the region is set to 
EMPTY, and arciRectangles is ignored. 

arciRectangles (PRECTL) - input 
Array of rectangles. 

The rectangles are specified in device coordinates. 

For each rectangle in the array, the value of xright must be greater than (or equal to) xleft, and 
ytop must be greater than (or equal to) ybottom. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 

PMERRJNVHPS 

PMERRPSBUSY 

P M E R R_IN V_LENGTH_OR_COU N T 

PMERRJNVHRGN 

PMERRINVCOORDINATE 

PMERRJNVRECT 

PMERRREGIONISCLIPREGION 

PMERRHRGNBUSY 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid length or count parameter was specified. 

An invalid region handle was specified. 

An invalid coordinate value was specified. 

An invalid rectangle parameter was specified. 

An attempt was made to perform a region operation on a 
region that is selected as a clip region. 

An internal region busy error was detected. The region 
was locked by one thread during an attempt to access it 
from another thread. 
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GpiSetRegion - 
Set Region 


Remarks 

This function is similar to GpiCreateRegion, except that it changes an already existing region to be 
the logical-OR of the supplied rectangles, instead of creating a new region. 

The previous contents of the region are irrelevant. Points on the right-hand and top boundaries are 
not included in the changed region; points on the left-hand and bottom boundaries, that are not also 
on the right-hand or top boundaries, (that is, the top-left and bottom-right corner points) are included 

It is invalid if the specified region is currently selected as the clip region (by GpiSetClipRegion). 


Related Functions 

• GpiCombineRegion 

• GpiCreateRegion 

• GpiDestroyRegion 

• GpiEqualRegion 

• GpiOffsetRegion 

• GpiPaintRegion 

• GpiPtlnRegion 

• GpiQueryRegionBox 

• GpiQueryRegionRects 

• GpiRectlnRegion 

Example Code 

In this example we change the region to be the logical-or of a set of rectangles. 

Idefine INCL_GPIREGIONS 
linclude <0S2.H> 

Idefine maxrects 2 

BOOL flResult; /* success indicator. */ 

HPS hps; /* presentation space handle. */ 

HRGN hrgn; /* region handle. */ 

RECTL arclRect [maxrects] = {{201, 20L, 

40L, 40L}, 

{40L, 20L, 

60L, 40L}}; 

/* array of rectangle structures */ 

flResult = GpiSetRegion(hps, 

hrgn, 

(LONG)maxrects, 

/* array of two rectangles. */ 
arclRect); 
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GpiSetSegmentAttrs - 
Set Segment Attributes 


#define INCL_GPISEGMENTS /* Or use INCL_GPI or INCL_PM */ 

BOOL GpiSetSegmentAttrs (HPS hps, LONG ISegid, LONG lAttrlbute, LONG IValue) 

This function sets a segment attribute. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

ISegid (LONG) - input 
Segment identifier. 

The identifier of the segment whose attribute is to be updated. It must be greater than zero. 

lAttribute (LONG) - input 
Segment attribute. 

For details of the following attributes, see the GpiSetlnitialSegmentAttrs function. 

ATTR_DETECT ABLE Detectability 

ATTR_VISIBLE Visibility 

ATTR_CHAINED Chained 

ATTR_DYNAMIC Dynamic 

ATTR_FASTCHAIN Fast chaining 

ATTR_PROP_DETECTABLE Propagate detectability 

ATTR_PROP_VISIBLE Propagate visibility. 

IValue (LONG) - input 
Attribute value: 

ATTR_ON On/yes 

ATTR_OFF Off/no. 

Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRJNV HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_SEG_NAME An invalid segment identifier was specified. 

P M E R R_IN V_SEG_ ATTR An invalid attribute parameter was specified with 

GpiSetSegmentAttrs, GpiQuerySegmentAttrs, 
GpiSetlnitialSegmentAttrs, or 
GpiQuerylnitialSegmentAttrs. 

PM ER R_INV_SEG_ATTR_V ALU E An invalid attribute value parameter was specified with 

GpiSetSegmentAttrs or GpiSetlnitialSegmentAttrs. 
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Set Segment Attributes 


PMERR_SEG_NOT_FOUND The specified segment identifier did not exist 

PMERRJNV_MICROPS_FUNCTION An attempt was made to issue a function that is invalid in 

a micro presentation space. 

Remarks 

This function sets the value of one segment attribute for the specified segment. The segment can be 
any retained segment. 

If the identifier is that of the currently-open segment: 

■ In retain mode, this is valid. 

• In draw-and-retaln mode, the retained segment is updated, but there is no change to the 
immediate drawing. 

• In draw mode, it is invalid. 

(For a description of drawing mode, see GpiSetDrawingMode). 

When a segment is modified from nonchained to chained, it is added to the end of the drawing chain. 


Related Functions 

• GpiCallSegmentMatrix 

• GpiCloseSegment 

• GpiCorrelateSegment 

• GpiDeleteSegment 

• GpiDeleteSegments 

• GpiDrawSegment 

• GpiErrorSegmentData 

• GpiOpenSegment 

• GpiQuerySegmentAttrs 

• GpiSetlnitialSegmentAttrs 

• GpiSetSegmentPriority 
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GpiSetSegmentAttrs - 
Set Segment Attributes 


Example Code 

This function is used to set the current value of the specified attribute. 


Idefine INCL_GPISEGMENTS 
linclude <0S2.H> 


HPS hps; /* Presentation-space */ 

/* handle. */ 

LONG lSegid; /* Segment identifier; must */ 

/* be greater than 0. */ 

/* */ 

/* The name of the */ 

/* segment for which */ 

/* attribute information is to */ 
/* be returned. */ 

LONG lAttribute; /* attribute to be queried */ 

LONG lvalue; 

lAttribute = ATTRJISIBLE; 


lValue = GpiSetSegmentAttrs (hps, 

lSegid, 
lAttribute, 
ATTR_0N) ; 
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GpiSetSegmentPriority - 
Set Segment Priority 


#define INCL_GPISEGMENTS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetSegmentPriority (HPS hps, LONG ISegld, LONG IRefSegld, LONG lOrder) 


This function changes the position of a segment within the segment chain, or adds a segment to the 

chain. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

ISegld (LONG) - input 
Segment identifier. 

The identifier of the segment whose priority is to be changed; it must be greater than 0. 

IRefSegid (LONG) - input 

Reference segment identifier. 

The segment that identifies a position in the segment chain. The segment specified in the ISegid 
parameter is placed either immediately before or after this segment, depending on the value 
specified in the lOrder parameter. Specifying 0 for IRefSegid indicates that the position is to be 
the beginning or the end of the segment chain as defined by the value in the lOrder parameter. 

lOrder (LONG) - input 

Segment higher or lower. 

Specifies whether the segment named in the ISegid parameter is to be placed before or after the 
segment named in the IRefSegid parameter. Possible values are: 

LOWER_PRI The segment named in the ISegid parameter is to have a lower priority than the 
segment named in the IRefSegid parameter. The ISegid segment is placed 
before the IRefSegid segment. If 0 is specified in the IRefSegid parameter, the 
segment identified in the ISegid parameter is placed as the highest priority 
segment. 

HIGHER_PRI The segment named in the ISegid parameter is to have a higher priority than the 
segment named in the IRefSegid parameter. The ISegid segment is placed after 
the IRefSegid segment. If 0 is specified in the IRefSegid parameter, the segment 
identified in the ISegid parameter is placed as the lowest priority segment. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid segment identifier was specified. 

An invalid order parameter was specified with 
GpiSetSegmentPriority. 


Possible returns from WinGetLastError 

PMERRJNVHPS 

PMERRPSBUSY 

PMERRINVSEGNAME 

PMERRINVORDERINGPARM 
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GpiSetSegmentPriority 
Set Segment Priority 


PMERR_SEG_AND_REFSEG_ARE_SAME The segid and refsegid specified with 

GpiSetSegmentPriority were the same. 

PMERR_SEG_NOT_FOUND The specified segment identifier did not exist 

PMERR_INV_MICROPS_FUNCTION An attempt was made to issue a function that is invalid in 

a micro presentation space. 

Remarks 

The specified segment can be a segment that exists in the segment chain, or an unchained segment. 
The effect of this function on an unchained segment is to add it to the segment chain in the specified 
position. 

The application may redraw the picture by drawing the segment chain (see GpiDrawChain). This 
causes the segments in the chain to be processed from beginning to end, so that if segments 
overlap, later ones are placed on top of earlier ones (assuming a default mix mode) and therefore 
appear to have higher priority. Changing the position of the segment in the chain therefore has the 
effect of changing its priority to the end user. 


Related Functions 

• GpiDrawChain 

• GpiDrawDynamics 

• GpiDrawFrom 

• GpiOpenSegment 

• GpiQuerySegmentPriority 

Example Code 

This example finds the segment with the highest priority and places a segment just before it with a 
lower priority. 

Idefine INCL_GPI SEGMENTS 
linclude <0S2.H> 


HPS hps; /* Presentation-space */ 

/* handle. */ 

LONG 1 RefSegid; /* Reference-segment */ 

/* identifier. */ 

LONG laddSegid = 20L; 

LONG 1 Segid; 

lSegid = GpiQuerySegmentPriority (hps, 

/* find the segment with the highest */ 
/* priority. */ 

0 , 

HIGHER_PRI) ; 


Gpi SetSegmentPri ori ty (hps , 

1 RefSegid, 
laddSegid, 
L0WER_PRI ) ; 
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GpiSetSegmentTransformMatrix - 
Set Segment Transform Matrix 


#define INCL_GPITRANSFORMS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetSegmentTransformMatrix (HPS hps, LONG ISegld, LONG ICount, 

PMATRIXLF pmatlf array, LONG lOptions) 


This function sets the segment transform that normally applies to all of the primitives in the specified 
segment. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

ISegid (LONG) - input 
Segment identifier. 

This must be greater than 0. 

ICount (LONG) - input 
Number of elements. 

The number of elements to be used in the pmatlf array parameter. If ICount is less than 9, the 
elements omitted default to the corresponding elements of the identity matrix (see below). 
Specifying ICount = 0 denotes that the identity matrix is used. 

pmatlfarray (PMATRIXLF) - input 
Transformation matrix. 


The elements of the transform, in row order. The first, second, fourth, and fifth elements are of 
type FIXED, and have an assumed binary point between the second and third bytes. Thus, a 
value of 1.0 is represented by 65 536. Other elements are normal signed integers. If the 
presentation space coordinate format is GPIF_SHORT (see GpiCreatePS), these elements must 
be within the range —1 through +1. 

The third, sixth, and ninth elements, when specified, must be 0, 0, and 1, respectively. 

lOptions (LONG) - input 
Transform options. 

Specifies how the existing segment transform is to be modified by the transform defined by the 
pmatlfarray parameter. The new segment transform is computed, and the result stored back in 
the segment, replacing the existing value. When the segment is drawn, the stored segment 
transform is used to update the segment transform that is currently in effect, in an additive 
manner. Possible values are: 


TRANSFORM_REPLACE The previous default segment transform is discarded and replaced by 

the specified transform. 

TRANSFORM_ADD The specified transform is combined with the existing default 

segment transform, in the order (1) existing transform, (2) new 
transform. This option is most useful for incremental updates to 
transforms. 


TRANSFORM_PREEMPT The specified transform is combined with the existing default 

segment transform, in the order (1) new transform, (2) existing 
transform. 
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GpiSetSegmentT ran sform Matrix 
Set Segment Transform Matrix 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 


PMERRINVHPS 

PMERR_PS_BUSY 

PMERRINVSEGNAME 

PMERR_INV_MICROPS_FUNCTION 

PMERR_INV_LENGTH_OR_COUNT 

PMERRSEGNOTFOUND 

PMERRINVMATRIXELEMENT 

PMERR_INV_TRANSFORM_TYPE 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid segment identifier was specified. 

An attempt was made to issue a function that is invalid in 
a micro presentation space. 

An invalid length or count parameter was specified. 

The specified segment identifier did not exist 

An invalid transformation matrix element was specified. 

An invalid options parameter was specified with a 
transform matrix function. 


Remarks 

The matrix is used to update the segment transform of a retained segment, according to the value of 
the / Options parameter. 

The segment transform is actually a model transform that applies at the start of the segment. It can 
be overridden later in the segment with a GpiSetModelTransformMatrix function. 

This function specifies the transform as a one-dimensional array of ICount elements, being the first 
ICount elements of a 3-row by 3-column matrix ordered in rows. The order of the elements is: 

Matrix Array 


a b 0 
c d 0 
e f 1 


(a,b,0,c,d,0,e,f,l) 


The transform acts on the coordinates of the primitives in a segment, so that a point with coordinates 
(x,y) is transformed to the point: 

(a*x + c*y + e, b*x + d*y + f) 

The initial value of the transform of a segment is the Identity matrix, as shown below: 

Matrix Array 


1 0 0 
0 1 0 
0 0 1 


( 1 , 0 , 0 , 0 , 1 , 0 , 0 , 0 , 1 ) 
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Set Segment Transform Matrix 


If scaling values greater than unity are given (which only applies if the presentation space coordinate 
format, as set by the GpiCreatePS function, is GPIF_LONG) it is possible for the combined effect of 
this and any other relevant transforms to exceed fixed-point implementation limits. This causes an 
error. 

Segment transforms do not apply to primitives outside segments. 


Related Functions 

• GpiCallSegmentMatrix 

• GpiQueryModelTransformMatrix 

• GpiQuerySegmentTransformMatrix 

• GpiSetModelTransformMatrix 

Example Code 

This example sets the transformation matrix of the highest priority segment to scale everything by a 
factor of 2. 

Idefine INCL_GPISEGMENTS 
linclude <0S2.H> 

HPS hps; /* Presentation-space */ 

/* handle. */ 

LONG lSegid; /* Segment identifier. */ 

MATRIXLF matlf Array = {MAKEFIXED(2,0) , 

0,0,0,MAKEFIXED(2,0), 

0 , 0 , 0 , 1 }; 

/* array of Transform matrix */ 

/* structures. */ 

lSegid = GpiQuerySegmentPriority(hps, 

/* find the segment with the highest */ 

/* priority. */ 

0 , 

HIGHER_PRI) ; 


Gpi SetSegmentTransformMatri x(hps , 

lSegid, 

9L, 

Smatlf Array) ; 
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GpiSetStopDraw 
Set Stop Draw 


#define INCL_GPICONTROL /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetStopDraw (HPS hps, LONG IValue) 


This function sets or clears the “stop draw” condition. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

IValue (LONG) - input 
Stop draw condition: 

SDW_OFF Clear the “stop draw” condition 
SDW_ON Set the “stop draw” condition. 

Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERR_INV_HPS An invalid presentation-space handle was specified. 

PMERR_INV_STOP_DRAW_VALUE An invalid value parameter was specified with 

GpiSetStopDraw. 

PMERRJNV_MICROPS_FUNCTION An attempt was made to issue a function that is invalid in 

a micro presentation space. 

Remarks 

This function allows an application to set up, and control, an asynchronous thread on which long 
drawing operations may be performed. At the point at which the controlling thread stops a draw, it 
sets the “stop draw” condition. The controlling thread clears this condition after it has received an 
acknowledgment from the drawing thread. 

The “stop draw” condition has no effect on any other calls. 

If one of the following calls is made (or has already been initiated from another thread) to the same 
presentation space, the call is terminated if the “stop draw” condition exists: 

• GpiDrawChain 

• GpiDrawDynamics 

• GpiDrawFrom 

• GpiDrawSegment 

• GpiPlayMetaFile 

• GpiPutData. 

The call terminates with a warning. 

Any call other than GpiSetStopDraw, directed at a presentation space that is currently in use, gives a 
PMERR_PS_BUSY error condition. 

Note: If this function is issued when an asynchronous draw to a metafile is taking place, the result is 
an unusable metafile. 
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Set Stop Draw 


Related Functions 

• GpiDrawChain 

• GpiDrawDynamics 

• GpiDrawFrom 

• GpiDrawSegment 

• GpiPlayMetaFile 

• GpiPutData 

• GpiQueryStopDraw 

Example Code 

This example shows how to stop drawing. 

Idefine INCL_GPICONTROL 
linclude <0S2.H> 

HPS hps; /* Presentation-space */ 

/* handle. */ 

GpiSetStopDraw(hps,SDW_OFF); 
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GpiSetTag 
Set Tag 


#define INCL_GPICORRELATION /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetTag (HPS hps, LONG ITag) 


This function specifies a tag by which the following primitives are to be known. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

ITag (LONG) - input 
Tag identifier. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERR_INV_HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_MICROPS_FUNCTION An attempt was made to issue a function that is invalid in 

a micro presentation space. 

Remarks 

When GpiCorrelateChain, GpiCorrelateFrom, or GpiCorrelateSegment is used to locate an object, 
both the segment identifier and the primitive tag of the object are returned to the application 
program. 

If a tag of 0 is specified, the primitives have no name and are not returned by the correlate call. 

Initially, the default and current tag are 0. The default tag can be changed with GpiSetDefTag. 

Primitives within an unnamed segment cannot be picked or correlated, and any tag applied to them 
is ignored. 

This function is not allowed between GpiBeginArea and GpiEndArea calls, therefore, all primitives 
within an area have the same tag. 

The attribute mode (see GpiSetAttrMode) determines whether the current value of the tag is 
preserved. 


Related Functions 

• GpiQueryDefTag 

• GpiQueryTag 

• GpiSetDefTag 

• GpiCorrelateChain 
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GpiSetTag - 
Set Tag 


Graphic Elements and Orders 

Element Type: OCODE_GSPIK 

This element type is generated if the attribute mode (see GpiSetAttrMode) is set to 
AM_NOPRESERVE. 

Order: Set Pick Identifier 

Element Type: OCODE_GPSPIK 

This element type is generated if the attribute mode is set to AM_PRESERVE. 

Order: Push and Set Pick Identifier 

Example Code 

This example opens a segment and calls GpiSetTag so that all of the following primitives will be 
associated with that tag. 

Idefine INCL_GPICORRELATION 
linclude <0S2.H> 

HPS hps; /* Presentation-space */ 

/* handle. */ 


Gpi OpenSegment ( hps , 0L) ; 
GpiSetTag (hps, 0L); 
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GpiSetT extAlignment 
Set Text Alignment 


#define INCL_GPIPRIMITIVES /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetT extAlignment (HPS hps, LONG (Horizontal, LONG IVertlcal) 


This function determines the alignment used to position the characters in a string. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

(Horizontal (LONG) - input 
Horizontal alignment: 


This parameter and the next one (/Vertical) specify the alignment of character strings 
horizontally and vertically. Together they define a reference point within the string that is 
positioned on the starting point specified for the string. 

Note: The terms used in this definition (left, right, top and bottom) must be interpreted with 
regard to the direction of the current coordinate system, as follows: 


Left the side of the display corresponding to the lowest x-value. 

Right the side of the display corresponding to the highest x-value. 

Top the side of the display corresponding to the highest y-value. 

Bottom the side of the display corresponding to the lowest y-value. 


TANORMALHORIZ 


TALEFT 


Normal alignment. This is the initial default. The alignment assumed 
depends on the current character direction as set by 
GpiSetCharDirection: 


CHDIRNLEFTRIGHT 

CHDIRNTOPBOTTOM 

CHDIRNRIGHTLEFT 

CHDIRNBOTTOMTOP 


Same as TA_LEFT. 

Same as TA jjS.CENTER. 
Same as TA_RIGHT. 
Same as TA_CENTER. 


Left alignment. The string is aligned on the left edge of its leftmost 
character. 


TA_CENTER 


Center alignment. The string is aligned on the arithmetic mean of Left 
and Right. 


TA_RIGHT 


Right alignment. The string is aligned on the right edge of its rightmost 
character. 


TA_STANDARD_HORIZ Standard alignment. This is the initial default. The alignment assumed 
depends on the current character direction: 


CHDIRN_LEFTRIGHT 

CHDIRNTOPBOTTOM 

CHDIRN_RIGHTLEFT 

CHDIRNBOTTOMTOP 


Same as TA_LEFT. 
Same as TA_US.LEFT. 
Same as TA_RIGHT. 
Same as TA_LEFT. 
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Set Text Alignment 


IVertical (LONG) - input 
Vertical alignment: 

TA_NORMAL_VERT 


Normal alignment. This is the initial default. The alignment assumed 
depends on the current character direction as set by 
GpiSetCharDirection: 


CHDIRNLEFTRIGHT 
CHDIRNTOPBOTTOM 
CHDIRNRIGHTLEFT 
CHDIRN BOTTOMTOP 


Same as TA_BASE. 
Same as TAJJS.TOP. 
Same as TA_BASE. 
Same as TA BOTTOM. 


TA_TOP 


Top alignment. The string is aligned on the top edge of its topmost 
character. 


TA_HALF Half alignment. The string is aligned on the arithmetic mean of Bottom 

and Top. 

TA_BASE Base alignment. The string is aligned on the base of its bottom 

character. 


TA_BOTTOM 


Bottom alignment. The string is aligned on the bottom edge of its bottom 
character. 


TA_STANDARD_VERT Standard alignment. This is the initial default. The alignment assumed 
depends on the current character direction: 


CHDIRNJ.EFTRIGHT 

CHDIRNTOPBOTTOM 

CHDIRN.RIGHTLEFT 

CHDIRNBOTTOMTOP 


Same as TA_BOTTOM. 
Same as TAJJS.TOP. 
Same as TAJ30TT0M. 
Same as TA_BOTTOM. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 

PMERRJNV_HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERRJNV_CHAR_ALIGN_ATTR The text alignment attribute specified in 

GpiSetTextAlignment is not valid. 


Remarks 

This function must not be issued in an area bracket. The attribute mode determines whether the 
current value of the text alignment attribute is preserved. 

Support for this function is device dependent. 
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GpiSetT extAlignment 
Set Text Alignment 


Related Functions 

• GpiQueryTextAlignment 

• GpiSetCharBox 

• GpiSetCharDirection 

• GpiSetCharMode 

• GpiSetCharSet 

• GpiSetCharShear 

• GpiPop 

• GpiSetAttrMode 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiSetBackColor 

• GpiSetBackMix 

• GpiSetColor 

• GpiSetMix 

• GpiCharString 

• GpiCharStringAt 

• GpiCharStringPos 

• GpiCharStringPosAt 

• GpiQueryCharStringPos 

• GpiQueryCharStringPosAt 

Graphic Elements and Orders 

Element Type: OCODE_GSTA 

This element type is generated if the attribute mode (see GpiSetAttrMode) is set to 
AM_NOPRESERVE. 

Order: Set Text Alignment 

Element Type: OCODE_GPSTA 

This element type is generated if the attribute mode is set to AM_PRESERVE. 
Order: Push and Set Text Alignment 
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GpiSetViewingLimits - 
Set Viewing Limits 


#define INCL_GPITRANSFORMS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiSetViewingLimits (HPS hps, PRECTL prciLimlts) 


This function establishes a clipping rectangle in model space. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

prciLimlts (PRECTL) - input 

Viewing limits in model space. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRJNV HPS An invalid presentation-space handle was specified. 

PMERR_PS_BUSY An attempt was made to access the presentation space 

from more than one thread simultaneously. 

PMERR_INV_COORDINATE An invalid coordinate value was specified. 

Remarks 

Viewing limits can be set within a segment, and apply to all subsequent primitives in the segment 
and any segments it calls. They can be changed at any time within the segment and they are not 
subject to segment or model transformations. Limits specified in called segments override those set 
by the limits of the root segment. 

The limits are reset to their default value at the start of each root segment, subject to the 
fast-chaining attribute, like primitive attributes. The initial default value is no clipping; this can be 
changed with GpiSetDefViewingLimits. 

The boundaries are inclusive, so that points on them are not clipped (removed). If either the left 
boundary of prcILimits is greater than the right, or the bottom greater than the top, a NULL rectangle 
is defined. Ail points are clipped. 

Attribute mode (see GpiSetAttrMode) has no effect on this function. 

The viewing limits are converted under the current viewing and default viewing transformations to a 
clipping rectangle in the page. This remains in force until changed by a subsequent 
GpiSetViewingLimits function. Clipping actually takes place to the intersection of the viewing limits, 
the clip path, the clip region, the graphics field, and the client area on the device. 
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GpiSetViewingLimits 
Set Viewing Limits 


Related Functions 

• GpiQueryViewingLimits 

• GpiSetDefViewingLimits 

• GpiSetGraphicsField 

Graphic Elements and Orders 

Element Type: OCODE_GSVW 

This element type Is generated if the attribute mode (see GpiSetAttrMode) is set to 
AM_NOPRESERVE. 

Order: Set Viewing Window 

Element Type: OCODE_GPSVW 

This element type is generated if the attribute mode is set to AM_PRESERVE. 
Order: Push and Set Viewing Window 

Example Code 

In this example the model space clipping region width is reduced to 400x400. 

fdefine I NC L_GP I TRANSFORMS 
linclude <0S2.H> 

HPS hps; /* Presentation-space */ 

/* handle. */ 

BOOL fSuccess; 

RECTL rclLimits = { /* viewing limits. */ 

10 , 10 , 

410,410 

}; 


fSuccess = GpiSetViewingLimits(hps, 

&rclLimits) ; 
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GpiSetViewingTransform Matrix - 
Set Viewing Transform Matrix 


#define INCL_GPITRANSFORMS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpISetVIe wlngT ransformMatrlx (HPS hps, LONG ICount, PMATRIXLF pmatlf Array, 

LONG lOptlons) 


This function sets the viewing transform that is to apply to any subsequently opened segments. 

Parameters 

hps (HPS) - input 

Presentation-space handle. 

ICount (LONG) - input 
Number of elements. 

The number of elements supplied in pmatlf Array, that are to be examined, starting from the 
beginning of the structure. If ICount is less than 9, remaining elements default to the 
corresponding elements of the identity matrix. Specifying ICount = 0 means that the identity 
matrix is used. 

pmatlfArray (PMATRIXLF) - input 
Transformation matrix. 

The elements of the transform, in row order. The first, second, fourth, and fifth elements are of 
type FIXED, and have an assumed binary point between the second and third bytes. Thus a 
value of 1.0 is represented by 65 536. Other elements are normal signed integers. If the 
presentation space coordinate format is GPIF_SHORT (see GpiCreatePS), these elements must 
be within the range —1 through +1. 

The third, sixth, and ninth elements, when specified, must be 0, 0, and 1, respectively. 

lOptlons (LONG) - input 
Transform option. 

Specifies how the specified transform is to be used to modify the existing viewing transform. 
This must be: 

TRANSFORM_REPLACE New and replace. The previous viewing transform is discarded and 

replaced by the specified transform. 

Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRJNVHPS 
PMERRPSBUSY 

PMERR_INV_MICROPS_FUNCTION 

P M ER R_IN V_LENGTH_OR_COUNT 
PMERRJNVMATRIXELEMENT 
PMERR_INV_TRANSFORM_TYPE 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An attempt was made to issue a function that is invalid in 
a micro presentation space. 

An invalid length or count parameter was specified. 

An invalid transformation matrix element was specified. 

An invalid options parameter was specified with a 
transform matrix function. 
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GpiSetViewingT ransformMatrix 
Set Viewing Transform Matrix 


PMERR_INV_IN_SEG An attempt was made to issue a function invalid inside a 

segment bracket. 

PMERR_NOT_IN_RETAIN_MODE An attempt was made to issue a segment editing element 

function that is invalid when the actual drawing mode is 
not set to retain 


Remarks 

This function is only valid outside segments. The viewing transform that is set applies to all 
subsequently opened (new) segments (it has no effect on primitives outside segments). All graphics 
primitives in a segment must have the same viewing transform. When it has been set for a particular 
segment, the viewing transform for that segment cannot be changed. 

The transform is specified as a one-dimensional array of ICount elements, being the first n elements 
of a 3-row by 3-column matrix ordered by rows. The order of the elements is: 


Matrix 


Array 


a b 0 
c d 0 
e f 1 


(a,b,0,c,d,O,e,f ,1) 


The transform acts on the coordinates of the primitives in a segment, so that a point with coordinates 
(x,y) is transformed to the point: 

(a*x + c*y + e, b*x + d*y + f) 

The initial value of the viewing transform is the identity matrix, as shown below: 


Matrix 


Array 


1 0 0 
0 1 0 
0 0 1 


( 1 , 0 , 0 , 0 , 1 , 0 , 0 , 0 , 1 ) 


The viewing transform must be set (or defaulted) to the unity transform, before any segment that is to 
be called is first opened. 

If scaling values greater than unity are given (which only applies if the presentation space coordinate 
format, as set by the GpiCreatePS function, is GPIF_LONG) it is possible for the combined effect of 
this and any other relevant transforms to exceed fixed-point implementation limits. This causes an 
error. 

This function must not be issued in a path or area bracket. 


Related Functions 

• GpiQueryViewingTransformMatrix 

• GpiSetDefauItViewMatrix 
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GpiSetViewingTransform Matrix - 
Set Viewing Transform Matrix 


Example Code 

In this example, the GpiSetViewingTransformMatrix is used to replace the existing viewing 
transformation. The new transformation will then double the width and height of drawing. 

Idefine INCL_GPITRANSFORMS 
linclude <0S2.H> 


HPS hps; /* Presentation space handle. */ 

LONG 1 Count; /* maximum number of elements */ 

MATRIXLF matlf = { MAKEFIXED(2,0) , /* scale x coordinates by a */ 

/* factor of 2. */ 

0, 0, 0, /* no rotation. */ 

MAKEFIXED(2,0) , /* scale y coordinates by a */ 

/* factor of 2. */ 

0, 0, 0, 1}; /* no rotation. */ 

Gpi SetVi ewi ngTransf ormMatr i x( hps , 

9L, /* number of elements. */ 

&matlf, 

TRANSFORM_REPLACE) ; 
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GpiStrokePath 
Stroke Path 


#define INCL_GPIPATHS /* Or use INCL_GPI or INCL_PM */ 


LONG GpiStrokePath (HPS hps, LONG IPath, ULONG flOptlons) 


This function strokes a path, and then draws it. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

IPath (LONG) - input 

Identifier of path to be stroked; it must be 1. 

flOptlons (ULONG) - input 
Stroke option: 

Reserved; must be 0. 

Returns 

Correlation and error indicators: 

GPI_OK Successful 

GPI_HITS Correlate hits 

GPI_ERROR Error. 

Possible returns from WinGetLastError 

PMERRINVHPS 
PMERRPSBUSY 

PMERR_INV_PATH_ID 
PMERRINVRESERVEDFIELD 
PMERR_PATH_UNKNOWN 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid path identifier parameter was specified. 

An invalid reserved field was specified. 

An attempt was made to perform a path function on a path 
that did not exist. 


Remarks 

The path is first converted to one that describes the envelope of a wide line stroked using the current 
geometric line-width attribute (see GpiSetLineWidthGeom). 

Note: This function and GpiModifyPath are the only calls that can cause geometric wide lines to be 
constructed. For more details about the way in which the envelope is constructed, see 
GpiModifyPath. 

The converted path is then filled, using winding mode area fill and the area attributes. The 
boundaries of the wide line are included in the fill. 

When it has been drawn, the path is deleted. 

This function is equivalent to GpiModifyPath, followed by GpiFillPath. It is provided to enable device 
drivers to optimize storage, if possible. 

If the current drawing mode (see GpiSetOrawingMode) is draw or draw-and-retaln, drawing occurs 
on the currently associated device. If the drawing mode is retain, this function is stored in the 
current segment and output occurs when the segment is subsequently drawn in the usual way. 
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GpiStrokePath - 
Stroke Path 


Related Functions 

• GpiBeginArea 

• GpiBeginPath 

• GpiEndPath 

• GpiFillPath 

• GpiModifyPath 

• GpiOutlinePath 

• GpiPathToRegion 

• GpiSetClipPath 

• GpiSetAttrs 

• GpiSetDefAttrs 

• GpiSetLineEnd 

• GpiSetLineJoin 

• GpiSetLineType 

• GpiSetLineWidth 

• GpiSetLineWidthGeom 

Graphic Elements and Orders 

Element Type: OCODE_GFPTH 

Note that GpiFillPath also generates this element type. 

Order: Fill Path 

Example Code 

This example uses the GpiStrokePath function to draw a wide line. 

fdefine INCL_GPIPATHS 
linclude <0S2.H> 

HPS hps; /* Presentation space handle. */ 

POINTL ptl Start = { 0, 0 }; 

POINTL ptlTriangle[] = { 100, 100, 200, 0, 0, 0 }; 

/* create the path */ 

GpiBeginPath(hps, 1L); 

Gpi Move (hps, &ptl Start); 

GpiPolyLine(hps, 3, ptlTriangle) ; 

GpiEndPath(hps) ; 

GpiSetLineWidthGeom(hps, 20L); /* set the line width */ 

GpiStrokePath(hps, 1L, 0L); /* draw the wide line */ 
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GpiTranslate - 
Translate Matrix 


#define INCL_GPITRANSFORMS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiTranslate (HPS hps, PMATRIXLF pmatlf Array, LONG lOptlons, 
PPOINTL pptITranslatlon) 


This function applies a translation to a transform matrix. 


Parameters 

hps (HPS) - input 

Presentation-space handle. 

pmatlf Array (PMATRIXLF) - input/output 
Transform matrix. 

The elements of the transform, in row order. The first, second, fourth, and fifth elements are of 
type FIXED, and have an assumed binary point between the second and third bytes. Thus a 
value of 1.0 is represented by 65 536. Other elements are normal signed integers. 

The third, sixth, and ninth elements must be 0, 0, and 1 , respectively. 

lOptlons (LONG) - input 
Transform options. 

Specifies how the transform defined by the specified translation should be used to modify the 
previous transform specified by the pmatlf Array parameter. Possible values are: 

TRANSFORM_REPLACE The previous transform is discarded and replaced by the transform 

describing the specified translation. 

TRANSFORM_ADD The previous transform is combined with a transform representing 

the specified translation in the order (1) previous transform, (2) 
translational transform. This option is most useful for incremental 
updates to transforms. 

pptITranslatlon (PPOINTL) - input 
Translation. 

The coordinates of a point, relative to the origin, which defines the required translation. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERR INV TRANSFORM TYPE An invalid options parameter was specified with a 

transform matrix function. 
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GpiTranslate - 
Translate Matrix 


Remarks 

This function is a helper function which either applies a specified translational component to an 
existing transform matrix, or replaces the matrix with one that represents the specified translation 
alone. 

The transform is specified as a one-dimensional array of 9 elements that are the elements of a 3-row 
by 3-column matrix ordered by rows. The order of the elements are as follows: 

Matrix Array 


a b 0 
c d 0 
e f 1 


(a,b,0,c,d,O,e,f ,1) 


Transforms act on the coordinates of primitives, so that a point with coordinates (x,y) is transformed 
to the point: 

(a*x + c*y + e, b*x + d*y + f) 

The transform can be used in any call following: 

• GpiSetModelTransformMatrix 

• GpiSetSegmentTransformMatrix 

• GpiSetViewingTransform Matrix 

• GpiSetDefauitViewMatrix. 

Other similar helper functions are: 

• GpiScale to apply a scaling component 

• GpiRotate to apply a rotation component. 


Related Functions 

• GpiRotate 

• GpiScale 

• GpiSetModelTransformMatrix 

• GpiSetSegmentTransformMatrix 

• GpiSetDefauitViewMatrix 

• GpiSetViewingTransformMatrix 
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GpiTranslate - 
Translate Matrix 


Example Code 

This example translates the center of the picture back to the center of the page. 

Idefine I NCL_GPITRANSFORMS 
Idefine INCLJIINSYS 
linclude <0S2.H> 

HPS hps; /* Presentation space handle. */ 

MATRIXLF matlf; /* Current viewing transformation */ 

POINTL ptlPictCenter; 

/* determine the center of the page */ 

ptlPictCenter.x = WinQuerySysValue(HWND_DESKTOP, 

SV_CXFULLSCREEN)/2 - ptlPictCenter.x; 
ptlPictCenter. y = WinQuerySysValue(HWND_DESKTOP, 

SV_CYFULLSCREEN)/2 - ptl PictCenter.y; 

Gpi QueryVi ewi ngTransformMatri x (hps , 

9L, 

/* Translate the center of the picture back to the center of the */ 

/* page. */ 

&matl f) ; 

GpiTranslate(hps, 

&matlf, 

TRANSFORM_ADD, 

&ptlPictCenter) ; 


5-562 PM Programming Reference 



GpiUnloadFonts - 
Unload Fonts 


#define INCL_GPILCIDS /* Or use INCL_GPI or INCL_PM V 


BOOL GpiUnloadFonts (HAB hab, PSZ pszFllename) 


This function unloads any fonts previously loaded from the resource file by GpiLoadFonts. 

Parameters 

hab (HAB) - input 

Anchor-block handle. 

pszFllename (PSZ) - input 

Fully qualified file name of the font resource. 

The file name extension is .FON 

Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERR_FONT_FILE_NOT_LOADED An attempt was made to unload a font file that was not 

loaded. 

PMERR_OWN_SET_ID_REFS An attempt to unload a font failed because the setid is still 

being referenced. 

Remarks 

Before issuing this function, the application must: 

1. Issue GpiSetCharSet to a font other than one of those to be unloaded, for example, to the default 
font. 

2. Issue GpiDeleteSetld for each local identifier (Icid) that references one of the fonts (the 
LCID_ALL option can be used if all Icids are to be deleted). 

An error is returned if Icids that reference one of the fonts still exist for this application, and a 
warning is logged if Icids exist for another application. 


Related Functions 

Prerequisite Functions 

• GpiDeleteSetld 

• GpiSetCharSet 

Other Related Functions 

• GpiCreateLogFont 

• GpiLoadFonts 

• GpiQueryFontMetrics 

• GpiQueryFonts 

• GpiQueryKerningPairs 

• GpiQueryNumberSetlds 

• GpiQuerySetlds 

• GpiQueryWidthTable 
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GpiUnloadFonts 
Unload Fonts 


Example Code 

This function unloads any font(s) previously loaded from the resource file by GpiLoadFonts. 

Idefine INCL_GPILCIDS 
linclude <0S2.H> 

HAB hab; /* Anchor-block handle. */ 

char fntname[] = "HELVETICA. FON"; 


GpiUnloadFonts (hab, fntname); 
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GpiUnloadPublicFonts - 
Unload Public Fonts 


#define INCL_GPILCIDS /* Or use INCL_GPI or INCL_PM */ 


BOOL GpiUnloadPublicFonts (HAB hab, PSZ pszFllename) 


This function unloads one or more generally-available fonts from the specified resource file. See 
GpiLoadPublicFonts. 


Parameters 

hab (HAB) - input 

Anchor-block handle. 

pszFllename (PSZ) - input 
Filename. 

This is the fully-qualified name of the font resource. The file-name extension is .FON 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERR_FONT_FILE_NOT_LOADED An attempt was made to unload a font file that was not 

loaded. 

PMERR_SET_ID_REFS An attempt to unload a font failed because the setid is still 

being referenced. 

Remarks 

Before issuing this function, the application must: 

1 . Issue GpiSetCharSet to a font other than one of those to be unloaded, for example, to the default 
font. 

2. Issue GpiDeleteSetld for each local identifier (Icid) that references one of the fonts (the 
LCID_ALL option can be used if all Icids are to be deleted). 

An error is returned if Icids that reference one of the fonts still exist for this or any other application, 
and the unload fails. 

Note: If another application is using the fonts when this function is issued, so that the call fails, the 
fonts are likely to remain loaded until the next boot. This is true even if the other application 
has issued a GpiLoadPublicFonts, and will later issue a GpiUnloadPublicFonts, since the use 
count is not decremented when the call fails. 

It is also possible for one application to get details of the fonts with GpiQueryFonts, but then to 
fail to be able to use them with GpiCreateLogFont, because another application unloaded 
them with GpiUnloadPublicFonts in the time between the two calls. 
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GpiUnloadPublicFonts 
Unload Public Fonts 


Example Code 

This function unloads one or more generally-available fonts from the specified resource file. 

Idefine INCL_GPI LCIDS 
linclude <0S2.H> 

HAB hab; /* Anchor-block handle. */ 

char fntname[] = "HELVETICA. FON"; 


Gpi Uni oadPubl i cFonts (hab , fntname) ; 
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GpiWCBitBIt - 
World Coordinates Bit Bit 


#define INCL_GPIBITMAPS /* Or use INCL_GPI or INCL_PM. Also in COMMON section 7 


LONG GpiWCBitBIt (HPS hpsTarget, HBITMAP hbmSource, LONG ICount, PPOINTL aptiPoints, 
LONG IRop, ULONG fiOptions) 


This function copies a rectangle of bit-map image data. 


Parameters 

hpsTarget (HPS) - input 

Target presentation-space handle. 

hbmSource (HBITMAP) - input 
Source bit-map handle. 

It is an error if this bit map is currently selected into a memory device context. 

ICount (LONG) - input 
Point count. 

This count must be equal to 4. 

aptiPoints (PPOINTL) - input 
Point array 

Array of ICount points, in the order Txl, Tyl, Tx2, Ty2, Sxl, Syl, Sx2, Sy2. These are: 

Txl.Tyl Specify the bottom-left corner of the target rectangle in target world coordinates. 

Tx2,Ty2 Specify the top-right corner of the target rectangle in target world coordinates. 

Sxl, Syl Specify the bottom-left corner of the source rectangle in source device coordinates. 

Sx2,Sy2 Specify the top-right corner of the source rectangle in source device coordinates. 

IRop (LONG) - input 

Mixing function required. 

Each plane of the target can be considered to be processed separately. For any pel in a target 
plane, three bits together with the IRop values are used to determine the final value. These are 
the value of that pel in the Pattern (P) and Source (S) data and the initial value of that pel in the 
Target (T) data. For any combination of P, S, and T pel values, the final target value for the pel is 
determined by the appropriate IRop bit value as shown below: 


P ST (Initial) 


T (final) 


0 

0 

0 

0 

1 

1 

1 

1 


0 

0 

1 

1 

0 

0 

1 

1 


0 

1 

0 

1 

0 

1 

0 

1 


Index bit 0 (least significant) 
Index bit 1 
Index bit 2 
Index bit 3 
Index bit 4 
Index bit 5 
Index bit 6 

Index bit 7 (most significant) 
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World Coordinates Bit Bit 


The index formed in the above way determines the mixing required. Mnemonic names are 
available for commonly used mixes: 


ROP SRCCOPY 

/* 

SRC 


*/ 

ROP SRCPAINT 

/* 

SRC OR DST 


*/ 

ROP SRCAND 

/* 

SRC AND DST 


*/ 

ROP SRCINVERT 

/* 

SRC XOR DST 


*/ 

ROP SRCERASE 

/* 

SRC AND NOT (DST) 

*/ 

ROP NOTSRCCOPY 

/* 

NOT (SRC) 


*/ 

ROP NOTSRCERASE 

/* 

NOT (SRC) AND NOT (DST) 

*/ 

ROP MERGECOPY 

/* 

SRC AND PAT 


*/ 

ROP MERGEPAINT 

/* 

NOT (SRC) OR 

DST 

*/ 

ROP PATCOPY 

/* 

PAT 


*/ 

ROP PATPAINT 

/* 

NOT(SRC) OR 

PAT OR DST 

*/ 

ROP PATINVERT 

/* 

DST XOR PAT 


*/ 

ROP DSTINVERT 

/* 

NOT (DST) 


*/ 

ROP ZERO 

/* 

0 


*/ 

ROP ONE 

/* 

1 


*/ 


fiOptlons (ULONG) - input 
Options. 

How eliminated lines or columns are treated if a compression is performed. 

Flags 15 through 31 of flOptions can be used for privately-supported modes for particular 
devices. 


BBO_OR 

BBOAND 

BBOJGNORE 


The default. If compression is necessary, logical-OR eliminated rows or 
columns. This is useful for white on black. 

If compression is necessary, logical-AND eliminated rows or columns. This is 
useful for black on white. 

If compression is necessary, ignore eliminated rows or columns. This is useful 
for color. 


Returns 

Correlation and error indicators: 
GPI_OK Successful 

GPI_HITS Correlate hits 

GPI_ERROR Error. 


Possible returns from WinGetLastError 


PMERRJNVHPS 

PMERRPSBUSY 

PMERRJNV_LENGTH_OR_COUNT 

PMERRINVBITBLTMIX 

P M E R R_IN V_BITBLT_ST YLE 

PMERRBITMAPNOTFOUND 

PMERRINVCOORDINATE 

PMERRJNVRECT 

PMERRNOBITMAPSELECTED 


An invalid presentation-space handle was specified. 

An attempt was made to access the presentation space 
from more than one thread simultaneously. 

An invalid length or count parameter was specified. 

An invalid IRop parameter was specified with a GpiBitBIt 
or GpiWCBitBIt function. 

An invalid options parameter was specified with a 
GpiBitBIt or GpiWCBitBIt function. 

A attempt was made to perform a bit-map operation on a 
bit map that did not exist. 

An invalid coordinate value was specified. 

An invalid rectangle parameter was specified. 

An attempt has been made to operate on a memory 
device context that has no bit map selected. 
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PM ERR _INCORRECT_DC_TYPE 


PM ERR JNCOM PATIBLEBITMAP 


PMERRINVHBITMAP 

PMERRHBITMAPBUSY 


An attempt was made to perform a bit-map operation on a 
presentation space associated with a device context of a 
type that is unable to support bit-map operations. 

An attempt was made to select a bit map or perform a 
BitBIt operation on a device context that was 
incompatible with the format of the bit map. 

An invalid bit-map handle was specified. 

An internal bit map busy error was detected. The bit map 
was locked by one thread during an attempt to access it 
from another thread. 


Remarks 

A rectangle of bit-map image data is copied from a bit map, to a bit map selected into a device 
context associated with the target presentation space. Alternatively, the target presentation space 
can be associated with a device context that specifies a suitable raster device, for example, the 
screen. 

Note: In either case, both source and target device contexts must apply to the same physical device. 
It is an error if this device does not support raster operations. 

A rectangle is specified in device coordinates for the source bit map, and one in world coordinates 
for the target presentation space. The source rectangle is noninclusive; the left and lower 
boundaries in device space are included, but not the right and upper boundaries. Thus if the 
bottom-left is equal to the top-right, the rectangle is deemed to be empty. The target rectangle is 
“inclusive-inclusive”; that is, all boundaries are included in the rectangle. 

If the target rectangle, after transformation to device coordinates and adjustment for inclusivity, is 
not the same size as the source rectangle, then stretching or compressing of the data occurs. 
f /Options specifies how eliminated rows or columns of bits are to be treated if compression occurs. 
Note that the pattern data is never stretched or compressed. 

If there is a rotational effect in the transforms, the copy of the bit map is rotated accordingly. 

The target rectangle is transformed to device coordinates, and if any shear or rotation has occurred, 
this is then converted to an upright rectangle that bounds the transformed figure. This rectangle is 
used as the target of the operation. No inversion of the image takes place. 

These current attributes of the target presentation space are used (other than for converting between 
monochrome and color, as described below): 

• Area color 

• Area background color 

• Pattern set 

• Pattern symbol. 

The color values are used in conversion between monochrome and color data. This is the only 
format conversion performed by this function. The conversions are: 

• Output of a monochrome pattern to a color device. 

In this instance the pattern is converted first to a color pattern, using the current area colors: 

- source Is -» area foreground color 

- source Os -» area background color. 

• Copying from a monochrome bit map to a color bit map (or device). 

The source bits are converted as follows: 

- source Is -» image foreground color 

- source Os -» image background color. 
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GpiWCBitBIt - 
World Coordinates Bit Bit 


• Copying from a color bit map to a monochrome bit map (or device). 

The source bits are converted as follows: 

— source nonzeros -* image foreground color 

- source Os -» image background color. 

If the mix (IRop) does not call for a pattern, the pattern set and pattern symbol are not used. 

Neither the source nor the pattern is required when a bit map, or part of a bit map, is to be cleared to 
a particular color. 

If the mix does require both source and pattern, a three-way operation is performed. 

If a pattern is required, dithering may be performed for solid patterns in a color that is not available 
on the device. See GpiSetPattern. 

This function (unlike GpiBitBIt) can be drawn immediately, retained in segment store, or both of 
these, depending upon the drawing mode (see GpiSetDrawingMode). 

Note: There are restrictions on the use of this function when creating SAA-conforming metafiles; 
see “Metafile Restrictions” on page G-1. 

Related Functions 

• DevQueryCaps 

• GpiBitBIt 

• GpiCreateBitmap 

• GpiDeleteBitmap 

• GpiDrawBits 

• GpiLoadBitmap 

• GpiQueryBitmapBits 

• GpiQueryBitmapDimension 

• GpiQueryBitmapHandle 

• GpiQueryBitmapParameters 

• GpiQueryDeviceBitmapFormats 

• GpiSetBitmap 

• GpiSetBitmapBits 

• GpiSetBitmapDimension 

• GpiSetBitmapId 

• WinDrawBitmap 

• WinGetSysBitmap 

Graphic Elements and Orders 

Element Type: OCODE_GBBLT 
Order: Bltblt 
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GpiWCBitBIt - 
World Coordinates Bit Bit 


Example Code 

This function copies a rectangle of bit-map image data. This example uses GpiWCBitBIt to copy and 
compress a bit map in a presentation space. The function copies the bit map that is 100 pels wide 
and 100 pels high into a 50-by-50-pel rectangle at the location (300,400). Since the raster operation is 
ROP_SRCCOPY, GpiWCBitBIt replaces the image previously in the presentation-space rectangle. 

The function compresses the bit map to fit the new rectangle by discarding extra rows and columns 
as specified by the BBOJGNORE option. 

Idefine INCL_GPIBITMAPS 
linclude <0S2.H> 

HPS hps; 

HBITMAP hbm; 

POINTL aptl [4] = 

300, 400, 

350, 450, 

0 , 0 , 

100 , 100 }; 


/* Presentation space handle. */ 


{ 

/* lower-left corner of target */ 
/* upper-right corner of target */ 
/* lower-left corner of source */ 
/* upper-right corner of source */ 


GpiWCBitBIt (hps, 
hbm, 

4L, 
aptl , 

R0P_SRCC0PY, 
BBOJGNORE) ; 


/* presentation space */ 

/* bit-map handle */ 

/* four points needed to compress */ 

/* points for source and target rectangles */ 
/* copy source replacing target */ 

/* discard extra rows and columns */ 
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Chapter 6. Profile Functions 

The following table shows all the Profile (Prf) functions in alphabetic order. 


C Name 

PrfCloseProfile 

PrfOpenProfile 

PrfQueryProfile 

PrfQueryProfileData 

PrfQueryProfilelnt 

PrfQueryProfileSize 

PrfQueryProfileString 

PrfReset 

PrfWriteProfileData 

PrfWriteProfileString 


Chapter 6. Profile Functions 


6-1 


PrfCloseProfile 
Close Profile 


#define INCL_WINSHELLDATA /* Or use INCL_WIN or INCL_PM */ 


BOOL PrfCloseProfile (HINI hlnl) 


This function indicates that a profile is no longer available for use. 

Parameters 

hlnl (HINI) - input 

Initialization-file handle. 

After this function, the handle is no longer valid. 

Returns 

Success indicator: 

TRUE Successful completion. 

FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRINIFILE _IS_SYS_OR_USER User or system initialization file cannot be closed. 

PMERR_INVALID_INI_FILE_HANDLE An invalid initialization-file handle was specified. 

Remarks 

This function cannot be used to close the current user or system initialization files. 

Related Functions 

• PrfOpenProfile 

Example Code 

This example calls PrfCloseProfile to close a profile and makes it unavailable for use. 

fdefine INCL_WINSHELLDATA /* Window Shell functions */ 
linclude <os2.h> 

BOOL f Success; /* success indicator */ 

HINI hi ni ; /* initial ization-file handle */ 

f Success = PrfCloseProfile(hini); 
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PrfOpenProfile - 
Open Profile 


#define INCL_WINSHELLDATA /* Or use INCL_WIN or INCL_PM */ 


HINI PrfOpenProfile (HAB hab, PSZ pszFlleName) 


This function indicates that a file is available for use as a profile. 


Parameters 

hab (HAB) - input 

Anchor-block handle. 

pszFlleName (PSZ) - input 
User-profile file name. 

This must not be the same as the current user or system initialization file name. 

Returns 

Initialization-file handle. 

This handle is used on other calls to manipulate the profile file. 

NULLHANDLE Error occurred 
Other Initialization-file handle. 

Possible returns from WinGetLastError 

PMERROPENINGINIFILE 

PMERRMEMORYALLOC 
PMERR_INI_FILE_IS_SYS_OR_USER 

Remarks 

A user profile and a system profile are opened by the system, either at start-up time, or (in the case 
of the user profile) as a result of a PrfReset function, and are always available. Their handles are 
HINIJJSERPROFILE and HINI_SYSTEMPROFILE. Applications do not have to open or close the user 
profile or the system profile. 

The handle returned is only valid for the process issuing the PrfOpenProfile function. 

The PrfOpenProfile function can be used by an administrator’s application that is creating or 
modifying a profile for a user. 

It can also be used to create a back-up profile as follows: 

• Use the enumerate form of PrfQueryProfileData to obtain a list of application names in the profile 
being backed up. 

• Use the enumerate form of PrfQueryProfileData to obtain a list of key names for each of the 
application names. 

• Use PrfQueryProfileData for each application-name or key-name pair to read the appropriate 
data. 

• Use PrfWriteProfileData to write the data into the back-up profile. 


Unable to open initialization file (due to lack of disk space 
for example). 

An error occurred during memory management. 

User or system initialization file cannot be closed. 
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PrfOpenProfile 
Open Profile 


Related Functions 

• PrfCloseProfile 

• PrfQueryProfileData 

Example Code 

This example uses PrfOpenProfile to open and make available a profile for the file 'PROFILE.INI'. 


Idefine INCL_WINSHELLDATA /* Window Shell functions */ 
linclude <os2.h> 

HINI hini; /* initialization-file handle */ 
HAB hab; /* anchor-block handle */ 
char pszFileName[13] ; /* user-profile file name */ 


st rcpy ( pszFi 1 eName ."PROFILE.INI"); 
hini = PrfOpenProfile(hab.pszFileName) ; 
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PrfQueryProfile - 
Query Profile 


#define INCL_WINSHELLDATA /* Or use INCL_WIN or INCL_PM 7 


BOOL PrfQueryProfile (HAB hab, PPRFPROFILE pprfproProflle) 


This function returns a description of the current user and system profiles. 


Parameters 

hab (HAB) - input 

Anchor-block handle. 

pprfproProflle (PRFPROFILE) - input/output 
Profile names structure. 

The cchUserName and the cchSysName parameters of the PRFPROFILE data structure are set to 
the lengths of the respective file names, even if truncation occurs. If these fields are initialized 
to 0 by the application, then the pszUserName and pszSysName parameters are not inspected, 
and the application can then determine the sizes of the buffers required to hold the names on a 
second call. Otherwise, the pszUserName and pszSysName parameters must point to reserved 
areas of memory, and the cchUserName and cchSysName parameters must indicate the sizes of 
those areas. 

If the pszUserName or the pszSysName parameter is NULL, then there is no defined user or 
system profile, respectively. 


Returns 

Success indicator: 

TRUE Successful completion. 

FALSE Error occurred, or there was insufficient space to record the names, which have been 
truncated. 

Related Functions 

• PrfReset 
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PrfQueryProfile 
Query Profile 


Example Code 

This example calls PrfQueryProfile to obtain a description of the current user and system profiles, in 
this case querying the lengths of the user and system profile file names and placing the values in 
variables. 


Idefine INCL_WINSHELLDATA /* Window Shell functions */ 
linclude <os2.h> 

BOOL fSuccess; /* success indicator */ 
HAB hab; /* anchor-block handle */ 
PRFPROFILE pprfproProfile; /* Profile names structure */ 
ULONG ulUserNameLen; /* length of user file name */ 
ULONG ulSysNameLen; /* length of system file name */ 


/* initialize lengths so that query will return the buffer sizes*/ 
pprfproProfile.cchUserName = 0L; 
pprf proProf ile.cchSysName = 0L; 

fSuccess = PrfQueryProfile(hab, &pprfproProfile) ; 

if (fSuccess == TRUE) 

{ 

ulUserNameLen = pprfproProfile.cchUserName; 
ulSysNameLen = pprfproProf ile.cchSysName; 

} 
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PrfQueryProfileData - 
Query Profile Data 


#define INCL_WINSHELLDATA /* Or use INCL_WIN or INCL_PM */ 


BOOL PrfQueryProfileData (HINI hlnl, PSZ pszApp, PSZ pszKey, PVOID pBuffer, 

PULONG pulBufferMax) 


This function returns a string of binary data from the specified profile. 


Parameters 

hlnl (HINI) - input 

Initialization-file handle. 

Both the user profile and system profile are searched 
The user profile is searched 
The system profile is searched 
Initialization-file handle. 


HINI_PROFILE 

HINIUSERPROFILE 

HINISYSTEMPROFILE 

Other 


pszApp (PSZ) - input 
Application name. 

The name of the application for which the profile data is required. The name must match exactly 
with the name stored in the profile. There is no case-independent searching. 

If this parameter is NULL, this function enumerates all the application names present in the 
profile and returns the names as a list in the pBuffer parameter. Each application name is 
terminated with a NULL character and the last name is terminated with two successive NULL 
characters. In this case, the pulBufferMax parameter contains the total length of the list 
excluding the final NULL character. 

pszKey (PSZ) - input 
Key name. 

The name of the key for which the profile data is required. The name must match exactly with 
the name stored in the profile. There is no case-independent searching. 

If this parameter is NULL, and if pszApp is not equal to NULL, this call enumerates all key names 
associated with the named application and returns the key names, but not their values, as a list 
in the pBuffer parameter. Each key name is terminated with a NULL character and the last name 
is terminated with two successive NULL characters. In this case, the pulBufferMax parameter 
contains the total length of the list excluding the final NULL character. 

pBuffer (PVOID) - output 
Value data. 

A buffer in which the value corresponding to the key name is returned. The returned data is not 
null terminated, unless the value data is explicitly null terminated within the file. This function 
handles binary data. 

pulBufferMax (PULONG) - input/output 
Size of value data. 

This is the size of the buffer specified by the pBuffer parameter. If the call is successful, this is 
overwritten with the number of bytes copied into the buffer. 
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PrfQueryProflleData 
Query Profile Data 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 


PMERRINVALIDPARM 

PMERR_NOTJN_IDX 

PMERR CAN NOT CALL SPOOLER 


A parameter to the function contained invalid data. 

The application name, key-name or program handle was 
not found. 

An error occurred attempting to call the spooler 
validation routine. This error is not raised if the spooler 
is not installed. 


Remarks 

This function returns a string of binary data from the profile. The call searches the file for a key 
matching the name specified by the pszKey parameter, under the application heading specified by 
the pszApp parameter. 

Enumeration can be performed in exactly the same way as in the PrfQueryProfileString function. The 
enumeration returns application or key names irrespective of whether the data concerned is written 
with the PrfWriteProfileString function or the PrfWriteProfileData function. 

This function returns data that is written to the file using either the PrfWriteProfileString function or 
the PrfWriteProfileData function. 

If the pszApp parameter is NULL, this call enumerates all application names and constructs in the 
pBuffer parameter a list of application names. Each application name in the list is terminated with a 
null character. The last string in the list is terminated with two null characters. This function returns 
the length of the list, up to, but not including, the final null. If the enumerated application names 
exceed the available buffer space, the enumerated names are truncated, the enumerated list is not 
terminated with 2 bytes of zeros, and the fSuccess parameter is set to FALSE. In this case, pszKey is 
ignored. 

If the pszApp parameter is valid and if the pszKey is NULL, this function enumerates all key names 
associated with the pszApp parameter by constructing in the pBuffer parameter a list of key names. 
Each key name in the list is terminated with a null character. The last string in the list is terminated 
with two null characters. This function returns the length of the list, up to, but not including, the final 
null. If the enumerated key names exceed the available buffer space, the enumerated names are 
truncated, the enumerated list is not terminated with 2 bytes of zeros, and the fSuccess parameter is 
set to FALSE. 

Related Functions 

• PrfQueryProfileSize 

• PrfWriteProfileData 
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Prf Query Prof ileData - 
Query Profile Data 


Example Code 

This example calls PrfQueryProfileData to search the user and system profiles for the value of key 
'KEY' within the application 'APP' and return the value if found. 


#define INCL_WINSHELLDATA /* Window Shell functions */ 
#include <os2.h> 

BOOL fSuccess; /* success indicator */ 
HINI hini; /* initialization-file handle */ 
char pszApp[10]; /* application name */ 
char pszKey[10]; /* key name */ 
VOID *pBuffer; /* Value data */ 
ULONG pulBufferMax; /* Size of value data */ 


/* Both the user profile and system profile are searched */ 
hini = HINI_PROFILE; 

/* specify application and key names */ 

strcpy(pszApp,"APP"); 

strcpy(pszKey,"KEY"); 

fSuccess = PrfQueryProfileData(hini , pszApp, pszKey, pBuffer, 

&pulBufferMax) ; 
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PrfQueryProfilelnt - 
Query Profile Integer 


#define INCL_WINSHELLDATA /* Or use INCL_WIN or INCL_PM */ 


LONG PrfQueryProfilelnt (HINI hlnl, PSZ pszApp, PSZ pszKey, LONG IDefault) 


This function returns an integer value from the specified profile. 


Parameters 

hlnl (HINI) - input 

Initialization-file handle. 


HINI_PROFILE 

HINIUSERPROFILE 

HINISYSTEMPROFILE 

Other 


Both the user profile and system profile are searched 
The user profile is searched 
The system profile is searched 
Initialization-file handle. 


pszApp (PSZ) - input 
Application name. 

The name of the application for which the profile data is required. The name must match exactly 
with the name stored in the profile. There is no case-independent searching. 

pszKey (PSZ) - input 
Key name. 

The name of the key for which the profile data is required. The name must match exactly with 
the name stored in the profile. There is no case-independent searching. 

IDefault (LONG) - input 
Default value. 


This value is returned in / Result , if the key defined by pszKey cannot be found in the initialization 
file. 


Returns 

Key value specified in the initialization file. 

The value of the key specified by pszKey in the initialization file. 

If the value corresponding to the key is not an integer, / Result is 0. 

If the key-name value is a series of digits followed by non-numeric characters, /Result contains 
the value of the digits only. For example, “KeyName = 102abc” causes the value 102 to appear 
in / Result . 


Possible returns from WinGetLastError 

PMERRJNVALID PARM A parameter to the function contained invalid data. 

PMERR_NOT_IN_IDX The application name, key-name or program handle was 

not found. 


PMERR_CAN_NOT_CALL_SPOOLER An error occurred attempting to call the spooler 

validation routine. This error is not raised if the spooler 
is not installed. 
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PrfQueryProfilelnt - 
Query Profile Integer 


Remarks 

This function returns an integer value from the profile. The call searches the file for a key matching 
the name specified by the pszKey parameter, under the application heading specified by the pszApp 
parameter. When an integer is stored as a text string using the PrfWriteProfileString function, for 
example, “123,” the returned value is the number, 123. The call returns / Default if the 
application-name or key-name pair cannot be found. 

Note: The search is case-dependent. 

Related Functions 

• PrfQueryProfileData 

• PrfWriteProfileString 

Example Code 

This example calls to search the user and system profiles for the integer value of key 'KEY' within 
the application 'APP' and return the value if found; if not found, 0 is returned. 


#define INCL_WINSHELLDATA /* Window Shell functions */ 
linclude <os2.h> 

LONG 1 Result; /* key value */ 
HINI hini; /* initialization-file handle */ 
char pszApp[10]; /* application name */ 
char pszKey[10]; /* key name */ 
LONG lOefault; /* default return value */ 


/* Both the user profile and system profile are searched */ 
hini = HINI_PROFILE; 

/* specify application and key names */ 
strcpy (pszApp, "APP") ; 
strcpy(pszKey,"KEY") ; 

/* set default to 0 */ 
lOefault = 0; 

IResult = Prf0ueryProfile!nt(hini , pszApp, pszKey, lOefault); 
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PrfQueryProfileSize 
Query Profile Size 


#define INCL_WINSHELLDATA /* Or use INCL_WIN or INCL_PM */ 


BOOL PrfQueryProfileSize (HINI hlni, PSZ pszApp, PSZ pszKey, PULONG pDataLen) 


This function obtains the size in bytes of the value of a specified key for a specified application in the 
profile. 


Parameters 

hlnl (HINI) - input 

Initialization-file handle. 


HINI_PROFILE 

HINIUSERPROFILE 

HINISYSTEMPROFILE 

Other 


Both the user profile and system profile are searched 
The user profile is searched 
The system profile is searched 
Initialization-file handle. 


pszApp (PSZ) - input 
Application name. 

The name of the application for which the profile data is required. 

If the pszApp parameter is NULL, then the pDataLen parameter returns the length of the buffer 
required to hold the enumerated list of application names, as returned by the 
PrfQueryProfileString function when its pszApp parameter is NULL. In this case, the pszKey 
parameter is ignored. 

pszKey (PSZ) - input 
Key name. 

The name of the key for which the size of the data is to be returned. 

If the pszKey parameter is NULL, and if the pszApp parameter is not NULL, the pDataLen returns 
the length of the buffer required to hold the enumerated list of key names for that application 
name, as returned by the PrfQueryProfileString function when its pszKey parameter is NULL, 
and its pszApp parameter is not NULL. 

pDataLen (PULONG) - output 
Data length. 

This parameter is the length of the value data related to the pszKey parameter. If an error 
occurs, this parameter is undefined. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 


Possible returns from WinGetLastError 

PMERRJNVALID PARM 
PMERR_NOT_IN_IDX 


A parameter to the function contained invalid data. 

The application name, key-name or program handle was 
not found. 


PMERR CAN NOT CALL S POOLER An error occurred attempting to call the spooler 

validation routine. This error is not raised if the spooler 
is not installed. 
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PrfQueryProfileSize - 
Query Profile Size 


Remarks 

The pszApp parameter and pszKey parameter are case sensitive and must match the names stored 
in the file exactly. There is no case-independent searching. 

This function can be used before using the PrfQueryProfileString call or the PrfQueryProfileData call, 
to allocate space for the returned data. 

No distinction is made between data that is written using the PrfWriteProfileData function and the 
PrfWriteProfileString function. 


Related Functions 

• PrfQueryProfileData 

• PrfQueryProfileString 

Example Code 

This example calls PrfQueryProfileSize to search the user and system profiles for the value of key 
'KEY' within the application 'APP' and return the byte size of the value if found. 


fdefine INCL_WINSHELLDATA /* Window Shell functions */ 
linclude <os2.h> 

BOOL fSuccess; /* success indicator */ 
HINI hini; /* initialization-file handle */ 
char pszApp [10]; /* application name */ 
char pszKey [10]; /* key name */ 
ULONG pDataLen; /* data length */ 


/* Both the user profile and system profile are searched */ 
hini = HINI_PROFILE; 

/* specify application and key names */ 
strcpy(pszApp,"APP") ; 
st rcpy (pszKey, 11 KEY" ) ; 

fSuccess = PrfQueryProfileSize(hini , pszApp, pszKey, &pDataLen); 
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PrfQueryProfileString - 
Query Profile String 


#define INCL_WINSHELLDATA /* Or use INCL_WIN or INCL_PM */ 


ULONG PrfQueryProfileString (HINI hlni, PSZ pszApp, PSZ pszKey, PSZ pszDefault, 

PSZ pszBuffer, ULONG cchBufferMax) 


This function retrieves a string from the specified profile. 


Parameters 

hint (HINI) - input 

Initialization-file handle. 

Both the user profile and system profile are searched 
The user profile is searched 
The system profile is searched 
Initialization-file handle. 


HINI_PROFILE 

HINIUSERPROFILE 

HINISYSTEMPROFILE 

Other 


pszApp (PSZ) - input 
Application name. 

The name of the application for which the profile data is required. 

The search performed on the application name is always case-dependent. Names starting with 
the characters “PM_” are reserved for system use. 

If this parameter is NULL, this function enumerates all the application names present in the 
profile and returns the names as a list in the pszBuffer parameter. Each application name is 
terminated with a NULL character and the last name is terminated with two successive NULL 
characters. In this instance, the pulLength parameter contains the total length of the list 
excluding the final NULL character. 

pszKey (PSZ) - input 
Key name. 

The name of the key for which the profile data is returned. 

The search on key name is always case-dependent. 

If this parameter equals NULL, and if the pszApp parameter is not equal to NULL, this function 
enumerates all key names associated with the named application and returns the key names 
(not their values) as a list in the pszBuffer parameter. Each key name is terminated with a NULL 
character and the last name is terminated with two successive NULL characters. In this 
instance, the pulLength parameter contains the total length of the list excluding the final NULL 
character. 


pszDefault (PSZ) - input 
Default string. 

The string that is returned in the pszBuffer parameter, if the key defined by the pszKey 
parameter cannot be found in the profile. 

If the pointer to this parameter is passed as NULL, then nothing is copied into the pszKey 
parameter if the key cannot be found. pulLength is returned as 0 in this case. 

pszBuffer (PSZ) - output 
Profile string. 

The text string obtained from the profile for the key defined by the pszKey parameter. 
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PrfQueryProfileString - 
Query Profile String 


cchBufferMax (ULONG) - input 
Maximum string length. 

The maximum number of characters that can be put into the pszBuffer parameter, in bytes. If the 
data from the profile is longer than this, it is truncated. 

Returns 

String length returned. 

The actual number of characters (including the null termination character) returned in the 
pszBuffer parameter, in bytes. 

Possible returns from WinGetLastError 

PMERRINVALIDPARM 
PMERRBUFFERTOOSMALL 

PMERR_NOT_IN_IDX 

PMERR_CAN_NOT_CALL_S POOLER 


PMERRJNVALIDASCIIZ 

Remarks 

The call searches the profile for a key matching the name specified by the pszKey parameter under 
the application heading specified by the pszApp parameter. If the key is found, the corresponding 
string is copied. If the key does not exist, the default character string, specified by the pszDefault 
parameter, is copied. 

If the enumerated application names exceed the available buffer space, the enumerated names are 
truncated, the enumerated list is not terminated with 2 bytes of zeros, and the pulLength parameter 
is set to the number of bytes copied into the pszBuffer parameter. In this instance, the pszKey 
parameter is ignored. 

Note: If the enumeration cannot be performed for any reason, the default character string is not 
copied. 

This function returns the length of the list, up to, but not including, the final null. If the enumerated 
key names exceed the available buffer space, the enumerated names are truncated, the enumerated 
list is not terminated with 2 bytes of zeros, and the pulLength parameter is set to the number of bytes 
copied into the pszBuffer parameter. 

This function is case-dependent; thus the strings in the pszApp parameter and the pszKey parameter 
must match exactly. This avoids any code-page dependency. The application storing the data must 
do any case-independent matching. 

The enumeration call does not distinguish between data written with the PrfWriteProfileString 
function and the PrfWriteProfileData function. 

Related Functions 

• PrfWriteProfileString 


A parameter to the function contained invalid data. 

The supplied buffer was not large enough for the data to 
be returned. 

The application name, key-name or program handle was 
not found. 

An error occurred attempting to call the spooler 
validation routine. This error is not raised if the spooler 
is not installed. 

The profile string is not a valid zero-terminated string. 
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PrfQueryProfileString 
Query Profile String 


Example Code 

PrfQueryProfileString is issued twice to obtain the names of the default printer, the default 
presentation driver, and the queue associated with the printer. If any of these requests fails, the 
default values already defined in DEVOPENSTRUC are used. 

Idefine INCL_WINSHELLDATA 
linclude <0S2.H> 
char szTemp[80]; 
char szBuff [257] ; 

PCH ptscan; 

DEVOPENSTRUC dopPrinter = {"LPT1Q", 

(PSZ)"IBM4201", 

0L, 

(PSZ) "PM_Q_STD" , 

0L, 0L, 0L, 0L, 0L}; 

if (PrfQueryProfileString(HINI_PROFILE, 

(PSZ) "PM_SP00LER" , 

(PSZ) "PRINTER", 

NULL, 

(PSZ)szTemp, 

(LONG)sizeof(szTemp) 

)){ 

szTemp[strlen(szTemp)-l] = 0; 
i f ( PrfQuery Profi 1 eStri ng (HINI_PROFI LE , 

(PSZ) " PM_SPOOLER_PRINTER" , 

(PSZ)szTemp, 

NULL, 

(PSZ)szBuff, 

(LONG)sizeof(szBuff) 

)){ 

/* char * strchr( const char *, int ); */ 
ptscan = (PCH)strchr(szBuff, ';'); 
ptscan++; 

ptscan = (PCH)strchr(ptscan, (INT) 1 ;'); 
ptscan++; 

‘(ptscan + strcspn(ptscan, ".,;")) = 0; 
dopPrinter. pszLogAddress = ptscan; 

ptscan = (PCH)strchr(szBuff , (INT) 1 ;'); 
ptscan++; 

‘(ptscan + strcspn (ptscan, ".,;")) = 0; 
dopPrinter. pszDri verName = ptscan; 
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PrfReset - 

Reset Presentation Manager 


#define INCL_WINSHELLDATA /* Or use INCL_WIN or INCL_PM */ 


BOOL PrfReset (HAB hab, PPRFPROFILE pprfproProflle) 


This function defines which files are to be used as the user and system profiles. 


Parameters 

hab (HAB) - input 

Anchor-block handle. 

pprfproProflle (PRFPROFILE) - input 
Profile-names structure. 

This contains the names of the files to be used as the new Presentation Manager' (PM) profile 
files. Any valid file names can be used. A name that is not already fully qualified is taken to 
refer to the current directory. 

If the user profile file does not exist, a new file is created. 

The name of the system profile cannot be changed. It must be the name of the current system 
profile as returned by PrfQueryProfile. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERROPENINGINIFILE Unable to open initialization file (due to lack of disk space 

for example). 


Remarks 

This function causes the workstation to use different profiles. When the workstation is initialized, the 
names of the user and system profiles are taken from the PROTSHELL statement specified in 
CONFIG.SYS. PrfReset allows the profiles to be changed during operation of the workstation, for 
example by a logon application controlling multiple consecutive users of the system. 

After the PrfReset function completes, the system has a new set of preferences (for example screen 
colors), a newstart-up list, and new spooler parameters. 

The PrfReset function broadcasts the PL_ ALTERED message, which must be processed by all 
applications that read their default settings from the user or system profiles. 

Note: This will only change the default system values in the ini file. It is up to the applications to 
read the new default settings and reset them to their new values. 

For example, consider logon applications. On receipt of a PL_ALTERED message, they should carry 
out the following: 

• Read the new color settings from the new profiles, and set the new screen colors (and palettes) 
which should be refreshed. 


' Trademark of IBM Corporation 
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PrfReset - 

Reset Presentation Manager 


• Set the country information, for example the date and time format, which is read from the new 
profiles. 

• Other preferences, for example, those that affect the operations of the alarm and the mouse, 
should also update with the new settings held in the new profiles. 

This function requires the existence of a message queue. 


Related Functions 

• PrfQueryProfile 

Related Messages 

• PL_ALTERED 


Example Code 

This function defines which files are to be used as the user and system profiles. 

Idefine INCL_WINSHELLDATA 
#include <0S2.H> 

HAB hab; 

char userpro[] = "profi1e.ini"; 

PRFPROFILE profile; 


PrfQueryProfile(hab, &profile); /* get the system profile name */ 

/* which cannot be changed. */ 


profile.pszUserName = userpro; 
profile.cchSysName = sizeof(profile.pszUserName); 


PrfReset (hab, &profile); 
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PrfWriteProfileData - 
Write Profile Data 


#define INCL_WINSHELLDATA /* Or use INCL_WIN or INCL_PM */ 


BOOL PrfWriteProfileData (HINI hint, PSZ pszApp, PSZ pszKey, PVOID pData, 

ULONG cchDataLen) 


This function writes a string of binary data into the specified profile. 


Parameters 

hlnl(HINI) - input 

Initialization-file handle. 


HINI_PROFILE 

HINIUSERPROFILE 

HINISYSTEMPROFILE 

Other 


User profile 
User profile 
System profile 
Initialization-file handle. 


pszApp (PSZ) - input 
Application name. 

The case-dependent name of the application for which profile data is to be written. Names 
starting with the characters “PM_” are reserved for system use. 

pszKey (PSZ) - input 
Key name. 

The case-dependent name of the key for which profile data is to be written. 

This parameter can be NULL in which case all the pszKey or pData pairs associated with pszApp 
are deleted. 


pData (PVOID) - input 
Value data. 

This is the value of the pszKey or pData pair that is written to the profile. It is not 
zero-terminated, and its length is given by the cchDataLen parameter. 

If this parameter is NULL, the string associated with the pszKey parameter is deleted. 

cchDataLen (ULONG) - input 
Size of value data. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERR INVALID PARM A parameter to the function contained invalid data. 

PMERR_CAN_NOT CALL SPOOLER An error occurred attempting to call the spooler 

validation routine. This error is not raised if the spooler 
is not installed. 
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PrfWriteProfileData 
Write Profile Data 


Remarks 

Because of the binary nature of the data, the input data is not zero-terminated. The length provided 
is the only way to identify the length of the data. 


Related Functions 

• PrfQueryProfileSize 

Example Code 

This function deletes the profile data associated with application sample.exe 

Idefine INCL_WINSHELLDATA 
linclude <0S2.H> 

HAB hab; 


PrfWriteProfileData(HINI_USERPROFILE, 

"sample", /* application. */ 

NULL, 

NULL, 

OL); 
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PrfWriteProfileString - 
Write Profile String 


#define INCL_WINSHELLDATA /* Or use INCL_WIN or INCL_PM */ 


BOOL PrfWriteProfileString (HINI hlnl, PSZ pszApp, PSZ pszKey, PSZ pszData) 


This function writes a string of character data into the specified profile. 


Parameters 

hlnl (HINI) - input 

Initialization-file handle. 


HINI_PROFILE 

HINIUSERPROFILE 

HINISYSTEMPROFILE 

Other 


User profile 
User profile 
System profile 
Initialization-file handle. 


pszApp (PSZ) - input 
Application name. 

The case-dependent name of the application for which profile data is to be written. Names 
starting with the characters “ PM_” are reserved for system use. 

pszKey (PSZ) - input 
Key name. 

The case-dependent name of the key for which profile data is to be written. 

This parameter can be NULL, in which case all the pszKey or pszData pairs associated with the 
pszApp parameter are deleted. 

pszData (PSZ) - input 
Text string. 

This is the value of the pszKey or pszData pair that is written to the profile. 

If this parameter is NULL, the string associated with the pszKey is deleted (that is, the entry is 
deleted). 

If this parameter is not NULL, the string is used as the value of the pszKey or pszData pair, even 
if the string has zero length. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRINVALID PARM A parameter to the function contained invalid data. 

PMERR_CAN_NOT_CALL_SPOOLER An error occurred attempting to call the spooler 

validation routine. This error is not raised if the spooler 
is not installed. 
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PrfWriteProfileString 
Write Profile String 


Remarks 

If there is no application field in the file that matches the pszApp, a new application field is created 
before the pszKey or pszData entry is made. 

If the key name does not exist for the application, a new pszKey or pszData entry is created for that 
application. If the pszKey already exists in the file, the existing value is overwritten. 


Related Functions 

• PrfQueryProfileString 

Example Code 

This function deletes the profile string associated with application sample.exe 

Idefine INCL_WINSHELLDATA 
linclude <0S2.H> 

HAB hab; 


PrfWri teProfi 1 eStri ng ( HINI_USERPROFILE , 

"sample", /* application. */ 

NULL, 

NULL); 
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Chapter 7. Spooler Functions 


The following table shows how all of the Spooler functions are related within functional areas. The 
functions are in alphabetic order within these areas. 


C Name 

C Name 

Control 

SpIControl Device 

SplEnumQueueProcessor 

SpICopyJob 

SplHoIdJob 

SpICreateDevice 

SplHoldQueue 

SpICreateQueue 

SpIPurgeQueue 

SpIDeleteDevice 

SpIQueryDevice 

SpIDeleteJob 

SpIQueryJob 

SpIDeleteQueue 

SpIQueryQueue 

SplEnumDevice 

SpIReleaseJob 

SplEnumDriver 

SpIReleaseQueue 

SplEnumJob 

SpISetDevice 

SplEnumPort 

SpISetJob 

SplEnumPrinter 

SpISetQueue 

SplEnumQueue 


Job Submission 

SpIQmAbort 

SpIQmOpen 

SpIQmAbortDoc 

SpIQmStartDoc 

SpIQmClose 

SpIQmWrite 

SpIQmEndDoc 
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SpIControlDevice - 
Spooler Control Device 


#define INCL_SPL /* Or use INCL_PM */ 


SPLERR SpIControlDevice (PSZ pszComputerName, PSZ pszPortName, ULONG ulControl) 


This function cancels, holds, continues, or restarts a print device. 


Parameters 

pszComputerName (PSZ) - input 

Name of computer where print device is to be controlled. 

A NULL string specifies the local workstation. 

pszPortName (PSZ) - input 
Port name. 

ulControl (ULONG) - input 
Operation to perform. 

PRD_DELETE Delete current print job 

PRD_PAUSE Pause printing 

PRD_CONT Continue paused print job 

PRD_RESTART Restart print job. 


Returns 

NO_ERROR (0) 

ERROR_NOT_SUPPORTED (50) 
ERROR_BAD_NETPATH (53) 
NERR_NetNotStarted (2102) 
NERR_DestNotFound (2152) 
NERR_Destldle (2158) 
NERR_DestlnvalldOp (2159) 
NERR_ProcNoRespond (2160) 
NERR SpoolerNotLoaded (2161) 
NERR_lnvalldComputer (2351) 


No errors occurred. 

This request is not supported by the network. 

The network path cannot be located. 

The network program is not started. 

The print device cannot be found. 

This print device is idle and cannot accept control operations. 
This print device request contains an invalid control function. 
The queue processor is not responding. 

The spooler is not running. 

The computer name is invalid. 


Remarks 

A paused print device cannot accept new print jobs. 

If PRD_DELETE is attempted when there is no current print job, NERR_Destldle (2158) is returned. 
To control jobs on a remote server requires administrator privilege. 
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SpIControlDevice - 
Spooler Control Device 


Related Functions 

• SplEnumDevice 

• SpIQueryDevice 

Example Code 

This sample code demonstrates the result of various actions that can be performed on the print 
device by this function call. At the command line, a print device name is entered along with an action 
code. 

Idefine INCL_SPL 
Idefine INCL_SPLDOSPRINT 
linclude <os2.h> 

linclude <stdio.h> /* for printf function */ 

linclude <neterr.h> /* for error codes */ 

INT main (argc, argv) 

INT argc; 

CHAR *argv[] ; 

{ 

SPLERR splerr ; 

ULONG ul Control =0L ; 

PSZ pszComputerName = NULL ; 

PSZ pszPrintDeviceName ; 

/* Input a Print Device Name and an Action Code on the command line */ 
if (argc != 3) 

{ 

printf ("Syntax is: qcontrol PrintDeviceName ActionCode \n") ; 
printf("Action codes are: D-Delete, P-Pause, C-Continue, R-Restart\n\n") ; 

DosExi t( EXIT_PROCESS , 0 ) ; 

} 

/* Get the print device name from the first input parameter. */ 

pszPrintDeviceName = argv[l]; 

/* Get the action code from the second input parameter. */ 

switch (argv [2] [0] ) 

{ 

case 'D 1 : 

ul Control = PRD_DELETE ; 
break; 
case ‘ P ' : 

ul Control = PRD_PAUSE ; 
break; 
case 'C 1 : 

ul Control = PRD_C0NT ; 
break; 
case 'R 1 : 

ul Control = PRD_RESTART ; 
break; 
default: 

printf("Invalid code\n"); 

DosExi t( EXIT_PROCESS , 0 ) ; 

} 

/* Call the function with the parameters obtained from the command line. */ 
splerr = SplControlDevice(pszComputerName, pszPrintDeviceName, ulControl); 

/* If there is an error returned, print it. */ 

if (splerr != 0L) 

{ 

switch (splerr) 

{ 
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SpIControl Device - 
Spooler Control Device 


case NERR_DestNotFound : 

printf("Destination does not exist. \n") ; 
break; 

case NERR_DestIdle: 

printf(“This print device is idle - can't do control ops. \n") 
break; 
default: 

printf ("Errorcode = %ld\n",splerr); 

} 

} else { 

printf("The print job operation was performed. \n\n") ; 

} 

DosExit( EXIT_PROCESS , 0 ) ; 
return (splerr) ; 
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SpICopyJob - 
Spooler Copy Job 


#define INCL_SPL /* Or use INCL_PM */ 


SPLERR SpICopyJob (PSZ pszSrcComputerName, PSZ pszSrcQueueName, ULONG uiSrcJob, 
PSZ pszTrgComputerName, PSZ pszTrgQueueName, 

PULONG puiTrgJob) 


This function copies a job in a print queue. 


Parameters 

pszSrcComputerName (PSZ) - input 

Name of computer where job is to be copied from. 

A NULL string specifies the local workstation. 

pszSrcQueueName (PSZ) - input 

Name of queue where job is to be copied from. 

uiSrcJob (ULONG) - input 

Source Job identification number. 

pszTrgComputerName (PSZ) - input 

Name of computer where job is to be copied to. 

A NULL string specifies the local workstation. 

pszTrgQueueName (PSZ) - input 

Name of queue where job is to be copied to. 

A NULL string specifies the same queue as the original job. 

puiTrgJob (PULONG) - output 

Job identification number of new job. 


Returns 

NO_ERROR (0) 
ERRORACCESSDENIED (5) 
ERROR_NOT_SUPPORTED (50) 
ERROR _INVAUD_PARAMETER (87) 
NERR_NetNotStarted (2102) 
NERR_QNotFound (2150) 
NERR_JobNotFound (2151) 
NERR_SpoolerNotLoaded (2161) 
NERRJnvalidComputer (2351) 


No errors occurred. 

Access is denied. 

This request is not supported by the network. 
An invalid parameter is specified. 

The network program is not started. 

The printer queue does not exist. 

The print job does not exist. 

The spooler is not running. 

The computer name is invalid. 


Remarks 

Currently there is a restriction that a job can only be copied onto the same queue (and computer) as 
the original job. 
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SpICopyJob - 
Spooler Copy Job 


Related Functions 

• SplEnumJob 

• SplEnumQueue 

• SpIQueryJob 

• SpIQueryQueue 

Example Code 

This sample code will make a duplicate copy of the jobid that is entered at the prompt. Presently, 
there is a restriction that the job can only be duplicated on the same computer/queue; for example, a 
local job. 

Idefine INCL_SPL 
linclude <os2.h> 

linclude <stdio.h> /* for printf function */ 

linclude <stdlib.h> /* for atoi function */ 

INT main (argc, argv) 

I NT argc; 

CHAR *argv[] ; 

{ 

SPLERR splerr ; 

ULONG ulSrcJob, ulTrgJob ; 

PSZ pszSrcComputerName.pszTrgComputerName ; 

PSZ pszSrcQueueName.pszTrgQueueName ; 

if (argc != 2) 

{ 

printf ("Command is: copyjob J0BID\n"); 

DosExit( EXIT_PROCESS , 0 ) ; 

} 

pszSrcComputerName = (PSZ) NULL ; 

/* The only valid values at present for these three parameters is NULL */ 
pszSrcQueueName = (PSZ)NULL; 
pszTrgComputerName = (PSZ) NULL ; 
pszTrgQueueName = (PSZ) NULL ; 

/* Convert input parameter to a ULONG */ 

ulSrcJob = atoi ( argv[l] ); 

if (splerr = SplCopyJob(pszSrcComputerName, pszSrcQueueName, ulSrcJob, 
pszT rgComputerName , pszT rgQueueName , &ul TrgJob) ) 

{ 

printf ("Return code SpICopyJob = %d\n", splerr); 

} 

else 

{ 

printf ("New job ID is %d\n", ul TrgJob) ; 

} 

DosExit( EXIT_PROCESS , 0 ) ; 
return (splerr); 

} /* end main */ 
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SpICreateDevice - 
Spooler Create Device 


#define INCL_SPL /* Or use INCL_PM */ 


SPLERR SpICreateDevice (PSZ pszComputerName, ULONG ulLevel, PVOID pBuf, 

ULONG cbBuf) 


This function establishes a print device on the local workstation or a remote server. 

Parameters 

pszComputerName (PSZ) - input 

Name of computer where print device is to be added. 

A NULL string specifies the local workstation. 

ulLevel (ULONG) - input 
Level of detail provided. 

This must be 3. 

pBuf (PVOID) - input 
Data structure. 

cbBuf (ULONG) - input 

Size, in bytes, of data structure. 

Returns 

NO_ERROR (0) 

ERRORACCESSDENIED (5) 

ERROR_NOT_SUPPORTED (50) 

ERROR_BAD_NETPATH (53) 

ERROR_INVALID_PARAMETER (87) 

ERROR_INVALID_NAME (123) 

ERROR_INVALID_LEVEL (124) 

NERR_NetNotStarted (2102) 

NERR_BufTooSmall (2123) 

NERR_DestExlsts (2153) 

NERR_DestNoRoom (2157) 

NERR_SpoolerNotLoaded (2161) 

NERR_DestlnvalldState (2162) 

NERR_SpoolNoMemory (2165) 

NERR_DrlverNotFound (2166) 

NERR_BadDev (2341) 

NERR_lnvalldComputer (2351) 


No errors occurred. 

Access is denied. 

This request is not supported by the network. 

The network path cannot be located. 

An invalid parameter is specified. 

The computer name is invalid. 

The level parameter is invalid. 

The network program is not started. 

The API return buffer is too small. 

The print device already exists. 

The maximum number of print devices has been reached. 
The spooler is not running. 

This operation cannot be performed on the print device. 

A spooler memory allocation failure occurred. 

The device driver does not exist. 

The device is already in use as a communications device. 
The computer name is invalid. 


Chapter 7. Spooler Functions 7-7 





SpICreateDevice - 
Spooler Create Device 


Remarks 

The result of this function is the creation of a new print device definition. 

The printer is set up to print on the logical address (port) defined by pszLogAddr in PRDINF03. If 
pszLogAddr is NULL, the print device definition is created but is not connected to any logical 
address. In this case no printing can occur on that print device or from any print queue connected 
only to that print device. If a logical address is specified, it must already be defined in the 
PM_SPOOLER_PORTS section of the initialization file. 

Note: T o change the connection between a print device and a port, use SpISetDevice. 

The maximum length for a print device name is 32 characters. The use of a longer name results in 
ERROR_INVALID_NAME (123). 

All device drivers and queues specified with the print device must already be defined to the spooler. 
To add a remote print device requires administrator privilege. 


Related Functions 

• SpIDeleteDevice 

• SplEnumDevice 

• SplEnumDriver 

• SplEnumPort 


7-8 PM Programming Reference 



SpICreateDevice - 
Spooler Create Device 


Example Code 

This sample code creates a PRDINF03 structure with dummy parameters. This structure is then used 
to call SpICreateDevice to establish a print device on a local workstation. 

Idefine INCL_BASE 
Idefine INCL_DOSMEMMGR 
Idefine INCL_SPL 
Idefine INCL_SPLDOSPRINT 

linclude <os2.h> 

linclude <stdio.h> /* for printf function */ 
linclude <string.h> /* for strcpy function */ 

INT main (argc, argv) 

I NT argc; 

CHAR *argv[] ; 

{ 

ULONG splerr ; 

ULONG cbBuf; 

ULONG ul Level ; 

PSZ pszComputerName ; 

PSZ pszPrintDeviceName ; 

PRDINF03 prd3 ; 

if (argc != 2) 

{ 

printf ("Syntax: sdcrt DeviceName \n") ; 

DosExit( EXIT_PROCESS , 0 ) ; 

} 

/* We are going to create a print device on the local workstation. */ 
pszComputerName = (PSZ) NULL ; 


/* Get the name from the command line. */ 

pszPrintDeviceName = argv[l]; 

/* Level 3 is valid. We will use level 3. */ 

ul Level = 3; 

/* Get size of buffer needed for a PRDINF03 structure. */ 

cbBuf = sizeof (PRDINF03) ; 

/* Set up the structure with dummy parameters. */ 


strcpy( prd3.pszPrinterName , pszPrintDeviceName); 
prd3.pszUserName= "A. Best"; 
prd3 . psz LogAddr= " LPT1Q " ; 
prd3.uJobId=0; 

prd3.pszComment= "Test comment"; 
prd3.pszDrivers = "IBMNULL"; 
prd3.usTime0ut = 777; 

/* Make the cal 1 . */ 

splerr = SpICreateDevice (pszComputerName, ul Level, 

&prd3, cbBuf); 


/* Print out the results. */ 

if (splerr == N0_ERR0R) 

printfC'The device was successfully created."); 
else 

printf ("SpICreateDevice Error=%ld, cbNeeded=%ld\n" , 
splerr, cbBuf) ; 

DosExit( EXIT_PROCESS , 0 ) ; 
return (splerr); 
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SpICreateQueue - 
Spooler Create Queue 


#define INCL_SPL /* Or use INCL_PM */ 

SPLERR SpICreateQueue (PSZ pszComputerName, ULONG ulLevel, PVOID pbBuf, 

ULONG cbBuf) 

This function creates a new print queue on the local workstation or on a remote server. A remote 
server setup requires the LAN Requester and Server software. 

Parameters 

pszComputerName (PSZ) - input 

Name of computer where queue is to be created. 

A NULL string specifies a local workstation. 

ulLevel (ULONG) - input 
Level of detail provided. 

This must be 3 or 6. 

pbBuf (PVOID) - input 
Data structure. 

cbBuf (ULONG) - input 

Size, in bytes, of data structure. 

Returns 

NO_ERROR (0) No errors occurred. 

ERROR_NOT_SUPPORTED (50) This request is not supported by the network. 

ERROR JNVALID PARAMETER (87) An invalid parameter is specified. 

ERRORJNVALID NAME (123) The computer name is invalid. 

ERROR_INVALID_LEVEL (124) The level parameter is invalid. 

NERR_NetNotStarted (2102) The network program is not started. 

NERR_RedirectedPath (2117) The operation is invalid on a redirected resource. 

NERR_BufTooSmall (2123) The API return buffer is too small. 

NERR_DestNotFound (2152) The printer destination cannot be found. 

NERR QExIsts (2154) The printer queue already exists. 

NERR_SpoolerNotLoaded (2161) The spooler is not running. 

NERR_DestlnvalldState (2162) This operation cannot be performed on the print 

destination in its current state. 

NERR_SpoolNoMemory (2165) A spooler memory allocation failure occurred. 

NERR_DrlverNotFound (2166) The device driver does not exist. 

NERR_DataTypelnvalid (2167) The data type is not supported by the queue processor. 

NERR_ProcNotFound (2168) The queue processor is not installed. 

NERR_BadDev (2341) The requested device is invalid. 

NERR_CommDevlnUse (2343) This device is already in use as a communications device. 

NERRJnvalldComputer (2351) The computer name is invalid. 
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SpICreateQueue - 
Spooler Create Queue 


Remarks 

To create a queue on a remote server requires administrator privilege. 

Applications wanting to create print queues should use the level 3 or level 6 call with a PRQINF03 or 
PRQINF06 data structure. The following fields are required in PRQINF03 or PRQINF06: 

pszName 

uPriority 

uStartTime 

uUntilTime 

pszSepFile 

pszParms 

pszPrinters 

pszDriverName 

pDriverData. 

If a queue of the name specified in pszName already exists on pszComputerName, the call fails 
unless the queue is marked for deletion. In this case, the queue is not deleted, and the creation 
fields are used to perform a SpISetQueue function on the queue. 

If pszPrinters is NULL, the queue is created but not connected to any printer. 

The queue that is created has a status of PRQ3_PENDING even if the queue is not connected to a 
printer. 

pszDriverName can be a NULL string, in which case pDriverData is ignored. Otherwise 
pszDriverName must refer to the name of a device driver that is already defined in the initialization 
file (for example, “IBM4019”). 


Chapter 7. Spooler Functions 


7-11 



SpICreateQueue - 
Spooler Create Queue 


Related Functions 

• SpIDeleteQueue 

• SplEnumDevice 

• SplEnumDriver 

• SplEnumQueueProcessor 


Example Code 

This sample code creates a queue on the local workstation. The queue is created with dummy 
parameters. The name is entered at the command line. 

Idefine INCL_BASE 
Idefine INCL_SPL 
Idefine INCL_SPLDOSPRINT 

linclude <os2.h> 
linclude <stdio.h> 
linclude <string.h> 

INT main (argc, argv ) 

INT argc; 

CHAR *argv[] ; 

{ 

ULONG s pi err ; 

ULONG cbBuf; 

ULONG ul Level ; 

PSZ pszComputerName ; 

PSZ pszQueueName ; 

PRQINF03 prq3 ; 

if (argc != 2) 

{ 

printf("Syntax: sqcrt QueueName \n") ; 

DosExit( EXIT_PROCESS , 0 ) ; 

} 

pszComputerName = (PSZ)NULL ; 
ul Level = 3L; 

/* Get the queue name from the argument entered at */ 

/* the command line. */ 

pszQueueName = argv[l]; 

/* Determine the size of the needed buffer. */ 

cbBuf = si zeof (PRQINF03) ; 

/* Set up the structure with some dummy parameters. */ 

strcpy( prq3.pszName , pszQueueName); 

prq3.uPriority=7; 

prq3 . uStartTime=77 ; 

prq3.uUntilTime=777; 

prq3.pszSepFi 1 e="a: \\best\\exampl e . sep" ; 

prq3.pszParms=NULL; 

prq3 . pszPri nters=NULL ; 

prq3 . pszDri verName=NULL; 

prq3 . pDr i verData=NULL ; 
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Spooler Create Queue 


/* Make the call with the proper parameters. */ 

splerr = SpICreateQueue (pszComputerName, ul Level, 

&prq3, cbBuf); 

/* Print out the error return code and some other information. */ 
printf ("SpICreateQueue Error=%ld, cbNeeded=%ld\n", 
splerr, cbBuf) ; 

DosExit( EXIT_PROCESS , 0 ) ; 
return (splerr); 
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SpIDeleteDevice - 
Spooler Delete Device 


#define INCL_SPL /* Or use INCL_PM 7 


SPLERR SpIDeleteDevice (PSZ pszComputerName, PSZ pszPrlntDeviceName) 


This function deletes a print device. 

Parameters 

pszComputerName (PSZ) - input 

Name of computer where print device is to be deleted. 

A NULL string specifies the local workstation. 

pszPrlntDeviceName (PSZ) - input 
Name of Print Device. 

Returns 

NO_ERROR (0) 

ERRORACCESSDENIED (5) 

ERROR_NOT_SUPPORTED (50) 

ERROR_BAD_NETPATH (53) 

NERR_NetNotStarted (2102) 

NERR_DestNotFound (2152) 

NERR_SpoolerNotLoaded (2161) 

NERR_Destlnval IdState (2162) 

NERRJnvalldComputer (2351) 

Remarks 

If the print device is currently printing a job, SpIDeleteDevice fails and returns 
NE R R_Destl n val i dState (2162). 

To delete a print device on a remote server requires administrator privilege. 

Related Functions 

• SpICreateDevice 

• SplEnumDevice 


No errors occurred. 

Access is denied. 

This request is not supported by the network. 

The network path cannot be located. 

The network program is not started. 

The print device cannot be found. 

The spooler is not running. 

This operation cannot be performed on the print device. 
The computer name is invalid. 
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Example Code 

This sample code will delete the print device whose name is entered at the prompt. 

Idefine INCL_BASE 
Idefine INCL_DOSMEMMGR 
Idefine INCL_SPL 
Idefine INCL_SPLDOSPRINT 

linclude <os2.h> 
linclude <stdio.h> 
linclude <neterr.h> 

INT main (argc, argv) 

I NT argc; 

CHAR *argv[] ; 

{ 

SPLERR splerr= 0L; 

PSZ pszComputerName ; 

PSZ pszPrintDeviceName ; 

/* Check that the parameters were entered at the command line. */ 

if (argc != 2) 

{ 

printf ("Syntax: sddel PrintDeviceName \n"); 

DosExit( EXIT_PROCESS , 0 ) : 

} 

/* Computer name of NULL indicates the local computer. */ 

pszComputerName = (PSZ)NULL ; 

/* Set the PrintDeviceName to the value entered at the command line. */ 

pszPrintDeviceName = argv[l]; 

/* Make the call and print out the return code. */ 

spl err=Spl Del eteDevi ce (pszComputerName, pszPri ntDevi ceName) ; 
switch (spl err) 

{ 

case N0_ERR0R: 

printf("Print Device %s was deleted. \n", pszPrintDeviceName) ; 
break: 

case NERR_DestNotFound : 

printf("Destination does not exist. \n"); 
break: 

case NERR_DestInvalidState: 

printf("This operation can't be performed on the print device. \n"); 
break: 

case NERR_Spool erNot Loaded: 

printf ("The Spooler is not running. \n") ; 
break; 
default: 

printf("SplDeleteDevice Errorcode = %ld\n",splerr) ; 

} /* endswitch */ 

DosExit( EXIT_PROCESS , 0 ) ; 
return (spl err) ; 
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#define INCL_SPL /* Or use INCL_PM */ 


SPLERR SpIDeleteJob (PSZ pszComputerName, PSZ pszQueueName, ULONG ulJob) 


This function deletes a job from a print queue. 

Parameters 

pszComputerName (PSZ) - input 

Name of computer where job is to be deleted. 

A NULL string specifies the local workstation. 

pszQueueName (PSZ) - input 
Queue Name. 

uklob (ULONG) - input 

Job identification number. 

Returns 

NO_ERROR (0) 

ERROR ACCESS DENIED (5) 

ERROR_NOT_SUPPORTED (50) 

ERROR_BAD_NETPATH (53) 

N E R R NetNotStart ed (2102) 

NERR_JobNotFound (2151) 

NERR_ProcNoRespond (2160) 

NERR_SpoolerNotLoaded (2161) 

NERR_lnvalldComputer (2351) 

Remarks 

It is possible to delete a job that is currently printing. 

If the print queue on which the print job is submitted is pending deletion (following a SpIDeleteQueue 
call), and the print job is the last in the queue, this function has the additional effect of deleting the 
queue. 

A user with administrator privilege can delete any job. 

A job created locally can be deleted locally regardless of user privilege level, but can be deleted 
remotely only by an administrator. 

A remote job can be deleted by a user without administrator privilege only if the username of the 
person initiating the request is the same as the username of the person who created the job. 


No errors occurred. 

Access is denied. 

This request is not supported by the network. 
The network path cannot be located. 

The network program is not started. 

The print job does not exist. 

The queue processor is not responding. 

The spooler is not running. 

The computer name is invalid. 
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Related Functions 

• SpICopyJob 

• SplEnumJob 

• SpIQueryJob 


Example Code 

This sample code will delete the job id that is entered at the prompt. 


Idefine INCL_BASE 
#define INCL_SPL 
linclude <os2.h> 
linclude <stdio.h> 
linclude <neterr.h> 
linclude <stdlib.h> 


/* for printf function */ 
/* for error codes */ 
/* for atoi function */ 


INT main (argc, argv) 

INT argc; 

CHAR *argv[]; 

{ 

SPLERR splerr ; 

ULONG ul Job ; 

PSZ pszComputerName = NULL ; 

PSZ pszQueueName = NULL ; 


/* Get job id from the input argument. */ 
ulJob = atoi (argv [1] ) ; 


/* Call the function to do the delete. If an error is */ 

/* returned, print it. */ 

splerr = Spl Delete Job ( pszComputerName, pszQueueName, ulJob); 

if (splerr != N0_ERR0R) 

{ 

switch (splerr) 

{ 

case NERR_JobNotFound : 

printf("Job does not exist. \n" ) ; 
break; 

case NERR_JobInvalidState: 

printf (“This operation can't be performed on the print job.\n“); 
break; 
default: 

printfC'Errorcode = %ld\n",splerr) ; 

} /* endswitch */ 

} 

else 

{ 

printf (“Job %d was deleted.\n",ul Job) ; 

} /* end if */ 

DosExit( EXIT_PROCESS , 0 ) ; 
return (splerr); 
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#define INCL_SPL /* Or use INCL_PM */ 


SPLERR SpIDeleteQueue (PSZ pszComputerName, PSZ pszQueueName) 


This function deletes a print queue from the spooler. 

Parameters 

pszComputerName (PSZ) - input 

Name of computer where queue is to be deleted. 

A NULL string specifies the local workstation. 

pszQueueName (PSZ) - input 
Queue name. 

Returns 

NO_ERROR (0) 

ERRORACCESSDENIED (5) 

ERROR NOT SUPPORTED (50) 

ERROR BAD NETPATH (53) 

ERROR_INVALID_PARAMETER (87) 

NERR_NetNotStarted (2102) 

NERR_QNotFound (2150) 

NERR_SpoolerNotLoaded (2161) 

NERR_QlnvalldState (2163) 

NERR_lnvalldComputer (2351) 

Remarks 

If there are print jobs in the queue, SpIDeleteQueue marks the queue PRQ3_PENDING. No further 
jobs can then be added to the queue, which is deleted when all jobs are printed. A queue marked 
PRQ3_PENDiNG can be held, and jobs in the queue can be held, restarted, and repeated. 

If a queue is held and there are jobs on the queue, a SpIDeleteQueue function fails with 
NERR_QlnvalidState (2163). 

To delete a queue on a remote server requires administrator privilege on the remote server. 

Related Functions 

• SpICreateQueue 

• SplEnumQueue 

• SpIQueryQueue 


No errors occurred. 

Access is denied. 

This request is not supported by the network. 

The network path cannot be located. 

An invalid parameter is specified. 

The network program is not started. 

The printer queue does not exist. 

The spooler is not running. 

This operation cannot be performed on the print queue. 
The computer name is invalid. 
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Example Code 

This sample code will delete the queue name that is entered at the prompt. 

fdefine INCL_SPL 
finclude <os2.h> 

linclude <stdio.h> /* for printf function */ 

linclude <neterr.h> /* for error codes */ 

INT main (argc, argv) 

INT argc; 

CHAR *argv[] ; 

{ 

SPLERR splerr ; 

PSZ pszComputerName = NULL ; 

PSZ pszQueueName ; 

/* Get queue name from the input argument */ 
pszQueueName = argv[l]; 

/* Call the function to do the delete. If an error is returned, print it. 

*/ 

spl err=Spl Del eteQueue (pszComputerName , pszQueueName) ; 

if (splerr != 0L) 

{ 

switch (splerr) 

{ 

case NERR_QNotFound ; 

printf("Queue does not exist. \n") ; 
break; 

case NERR_QInval idState: 

printf ("This operation can't be performed on the print queue. \n"); 
break; 
default: 

printf("Errorcode = %ld\n", splerr); 

} /* endswitch */ 

} 

else 

{ 

printf ("Queue % s was deleted. \n", pszQueueName) ; 

} /* endif */ 

DosExit( EXIT_PROCESS , 0 ) ; 
return (splerr); 


Chapter 7. Spooler Functions 


7-19 


SplEnumDevice - 
Spooler Enumerate Device 


#define INCL_SPL /* Or use INCL_PM */ 


SPLERR SplEnumDevice (PSZ pszComputerName, ULONG ulLevel, PVOID pBuf, 
ULONG cbBuf, PULONG pcReturned, PULONG pcTotal, 
PULONG pcbNeeded, PVOID pReserved) 


This function lists print device on a server, optionally supplying status information. 


Parameters 

pszComputerName (PSZ) - input 

Name of computer where print devices are to be listed. 

A NULL string specifies the local workstation. 

ulLevel (ULONG) - input 
Level of detail required. 

This must be 0, 2 or 3. 

pBuf (PVOID) - output 
Buffer. 

cbBuf (ULONG) - input 
Size, in bytes, of Buffer. 

pcReturned (PULONG) - output 
Number of entries returned. 

pcTotal (PULONG) - output 
Number of entries available. 

pcbNeeded (PULONG) - output 

Size in bytes of available information. 

A value of 0 specifies that the size is not known. 

pReserved (PVOID) - output 
Reserved. 

This must be NULL. 


Returns 

NO_ERROR (0) 

ERROR_NOT_SUPPORTED (50) 
ERROR_BAD_NETPATH (53) 
ERROR_INVALID_PARAMETER (87) 
ERRORJNVALIDLEVEL (124) 
ERROR_MORE_DATA (234) 

N E R R NetNot Started (2102) 
NERR_SpoolerNotLoaded (2161) 
NERRJnvalldComputer (2351) 


No errors occurred. 

This request is not supported by the network. 
The network path cannot be located. 

An invalid parameter is specified. 

The level parameter is invalid. 

Additional data is available. 

The network program is not started. 

The spooler is not running. 

The computer name is invalid. 
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Remarks 

The buffer contents on return are: 

ulLevel Buffer Contents 

0 An array of port names of type PSZ. 

2 An array of print device names of type PSZ. 

3 An array of PRDINF03 structures. 

If no job is printing on the print device, bits 2-11 of fsStatus in the PRDINF03 data structure are 
meaningless. 


Related Functions 

• SpICreateDevice 

• SpIDeleteDevice 


Example Code 

This sample code enumerates all the devices on the local workstation. It then prints out the 
information. 

Idefine INCL_BASE 
Idefine INCL_DOSMEMMGR 
Idefine INCL_SPL 
Idefine INCL_SPLDOSPRINT 

linclude <os2.h> 
linclude <stdio.h> 
linclude <neterr.h> 

INT main () 

{ 

ULONG cbBuf ; 

ULONG cTotal ; 

ULONG cReturned ; 

ULONG cbNeeded ; 

ULONG ulLevel = 3L; 

ULONG i ; 

SPLERR splerr ; 

PSZ pszComputerName ; 

PBYTE pBuf ; 

PPRDINF03 pprd3 ; 

pszComputerName = (PSZ) NULL ; 

/* Make the call with cBuf = 0 so that you will get the size of the */ 

/* buffer needed returned in cbNeeded. */ 

splerr = SplEnumDevice(pszComputerName, ulLevel, pBuf, 0L, /* cbBuf */ 

ScReturned, fccTotal, ScbNeeded, 

NULL) ; 

/* Only continue if the error codes ERR0R_M0RE_DATA or */ 

/* NERR_BufTooSmall are returned. */ 

if (splerr == ERR0R_M0RE_DATA || splerr == NERR_BufTooSmall) 

{ 

/* Allocate memory for the buffer that will hold the returning info. */ 
if (!DosAllocMem( &pBuf, cbNeeded, 

PAG_READ | PAGJ/RITE | PAG_COMMIT) ) 

{ 

cbBuf = cbNeeded ; 

/* Make call again with the proper buffer size. */ 

splerr = SplEnumDevice(pszComputerName, ulLevel, pBuf, cbBuf, 
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&cReturned, &cTotal , 
&cbNeeded, NULL) ; 


/* If no errors, print out the buffer information, 
if (splerr == N0_ERR0R) 

{ 

for (i=0;i < cReturned ; i++) 

{ 


/* Each time through the loop increase the pointer. 
pprd3 = (PPRDINF03) pBuf +i ; 
printf ("Device info:pszPrinterName - %s\n", 
pprd3->pszPrinterName) ; 

printf(" pszUserName - %s\n", pprd3->pszUserName) ; 

printf(" pszLogAddr - %s\n", pprd3->pszLogAddr) ; 

printf (" uJobld - %d fsStatus - %X\n", 
pprd3->uJobId , pprd3->fsStatus) ; 
printf(" pszStatus - %s\n", pprd3->pszStatus) ; 

printf (" pszComment - %s\n", pprd3->pszComment) ; 

printf(" pszDrivers - %s\n", pprd3->pszDri vers) ; 

printf (" time - %d usTimeOut - %X\n", 

pprd3->time , pprd3->usTime0ut) ; 

} 


} 

DosFreeMem(pBuf) *, 

} 

} /* end if */ 
else 


{ 

printf("SplEnumDevice splerr=%ld, cTotal=%ld, cReturned=%ld, 
cbNeeded=%ld\n", 

splerr, cTotal, cReturned, cbNeeded) 

} 

DosExit( EXIT_PROCESS , 0 ) ; 
return (splerr) ; 

} /* end main */ 


*/ 


*/ 
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#define INCL_SPL /* Or use INCL_PM */ 


SPLERR SplEnumDriver (PSZ pszComputerName, ULONG ulLevel, PVOID pBuf, ULONG cbBuf, 
PULONG pcReturned, PULONG pcTotal, PULONG pcbNeeded, 

PVOID pReserved) 


This function lists printer presentation drivers on the local workstation or on a remote server. 

Parameters 

pszComputerName (PSZ) - input 

Name of computer where queues are to be listed. 

A NULL string specifies the local workstation. 

ulLevel (ULONG) - input 
Level of detail. 

The level of detail required. This must be 0. 

pBuf (PVOID) - output 
Buffer. 

cbBuf (ULONG) - input 
Size, in bytes, of Buffer. 

pcReturned (PULONG) - output 
Number of entries returned. 

pcTotal (PULONG) - output 

Total number of entries available. 

pcbNeeded (PULONG) - output 

Size in bytes of available information. 

A value of 0 specifies that the size is not known. 

pReserved (PVOID) - output 
Reserved. 

This must be NULL. 


Returns 

NO_ERROR (0) 

ERROR ACCESS DENIED (5) 
ERROR NOT SUPPORTED (50) 
ERROR_BAD_NETPATH (53) 
ERROR_INVALID_PARAMETER (87) 
ERROR_INVALID_LEVEL (124) 
ERROR_MORE_DATA (234) 
NERR_NetNotStarted (2102) 
NERR_BufTooSmall (2123) 
NERR_SpoolerNotLoaded (2161) 
NERRJnvalldComputer (2351) 


No errors occurred. 

Access is denied. 

This request is not supported by the network. 
The network path cannot be located. 

An invalid parameter is specified. 

The level parameter is invalid. 

Additional data is available. 

The network program is not started. 

The API return buffer is too small. 

The spooler is not running. 

The computer name is invalid. 
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Remarks 

The buffer contents on return are: 

ul Level Buffer Contents 

0 An array of PRDRIVINFO structures 

Related Functions 

• SpICreateDevice 

• SpICreateQueue 

• SpISetDevice 

• SpISetQueue 


Example Code 

This sample code will enumerate all the drivers on a local computer. 


fdefine INCL_BASE 
#def i ne INCL_DOSMEMMGR 
fdefine INCL_SPL 
fdefine INCL_SPLDOSPRINT 

finclude <os2.h> 

finclude <stdio.h> /* for printf function */ 

finclude <neterr.h> /* for error codes */ 

INT main () 

{ 

SPLERR splerr ; 

ULONG cbBuf ; 

ULONG cTotal ; 

ULONG cReturned ; 

ULONG cbNeeded ; 

ULONG i ; 

PSZ pszComputerName = NULL ; 

PSZ pszDri verName ; 

PBYTE pbuf ; 

/* Call the function the first time with zero in cbBuf. The count of bytes */ 
/* needed for the buffer to hold all the info will be returned in cbNeeded.*/ 
splerr = SplEnumDri ver(pszComputerName, 0L, NULL, 0L, 

&cReturned, &cTotal, &cbNeeded, 

NULL ); 

/* If the return code is ERR0R_M0RE_DATA or NERR_BufTooSmall , then 
all the */ 

/* parameters were correct; and we can continue. */ 

if (splerr == ERR0R_M0RE_DATA || splerr == NERR_BufTooSmall ) 

{ 

/* Allocate memory for the buffer to hold the returned information. Use */ 
/* the count of bytes that were returned by our first call. */ 

if (!DosAllocMem( Spbuf, cbNeeded, 

PAG_READ | PAG_WRITE | PAG_COMMIT ) ) 

{ 

/* Set count of bytes to the value returned by our first call. */ 

cbBuf= cbNeeded ; 

/* Now call the function a second time with the correct values, and */ 
/* the information will be returned in the buffer. */ 

splerr= SplEnumDri ver(pszComputerName, 0L, pbuf, cbBuf, 
fccReturned .ScTotal, ScbNeeded, 

NULL ) ; 

if (splerr == N0_ERR0R) 
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{ 

/* Set a pointer to point to the beginning of the buffer. */ 

pszDriverName = (PSZ)pbuf; 

/* Print the names that are in the buffer. The count of the number*/ 
/* of names in pBuf have been returned in cReturned. */ 

for ( i =0 ; i < cReturned ; i++) 

{ 

printf ("Driver name - %s\n", pszDriverName) ; 

/* Increment the pointer to point to the next name. */ 

pszDriverName += DRIV_NAME_SIZE +DRIV_DEVICENAME_SIZE 

+ 2 ; 

} 

} 

/* Free the memory allocated for the buffer. */ 

DosFreeMem(pbuf) ; 

} 

} 

else 

{ 

/* If the first call to the function returned any error code other */ 
/* than ERR0R_M0RE_DATA or NERR_BufTooSmall , we print the 
following. */ 

printf ("Spl EnumDriver error=%ld \n",splerr) ; 

} 

DosExit( EXIT_PROCESS , 0 ) ; 
return (spl err); 

} 
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#define INCL_SPL /* Or use INCL_PM */ 


SPLERR SplEnumJob (PSZ pszComputerName, PSZ pszQueueName, ULONG ulLevel, 

PVOID pBuf, ULONG cbBuf, PULONG pcReturned, PULONG pcTotal, 
PULONG pcbNeeded, PVOID pReserved) 


This function lists the jobs in a print queue, optionally supplying status information on each job. 


Parameters 

pszComputerName (PSZ) - input 

Name of computer where jobs are to be listed. 

A NULL string specifies the local workstation. 

pszQueueName (PSZ) - input 
Queue name. 

ulLevel (ULONG) - input 
Level of detail required. 

This must be 0 or 2. 

pBuf (PVOID) - output 
Buffer. 

cbBuf (ULONG) - input 
Size, in bytes, of Buffer. 

pcReturned (PULONG) - output 
Number of entries returned. 

pcTotal (PULONG) - output 
Number of entries available. 

pcbNeeded (PULONG) - output 

Size in bytes of available information. 

A value of 0 specifies that the size is not known. 

pReserved (PVOID) - output 

Reserved. This must be NULL. 


Returns 

NO_ERROR (0) 

ERROR_NOT_SUPPORTED (50) 
ERROR _INVALID_PARAMETER (87) 
ERRORJNVALIDLEVEL (124) 
ERROR_MORE_DATA (234) 

N ER R_NetNotStarted (2102) 
NERR_QNotFound (2150) 
NERR_SpoolerNotLoaded (2161) 
NERRJnvalldComputer (2351) 


No errors occurred. 

This request is not supported by the network. 
An invalid parameter is specified. 

The level parameter is invalid. 

Additional data is available. 

The network program is not started. 

The printer queue does not exist. 

The spooler is not running. 

The computer name is invalid. 
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Remarks 

The buffer contents on return are: 
ulLevel Buffer Contents 

0 An array containing a uJobld for each of pcReturned jobs. 

2 An array containing a PRJINF02 structure for each of pcReturned jobs. 

Related Functions 

• SpICopyJob 

• SpIDeleteJob 

• SpIQueryJob 

Example Code 

This sample code accepts a queue name from the command line, and then prints out all the 
information associated with each job in that queue. Level 0 and 2 are valid; we have chosen to print 
out level 2 information. 

Idefine INCL_SPL 
Idefine INCL_SPLDOSPRINT 

linclude <os2.h> 

linclude <stdio.h> /* for printf function */ 

linclude <neterr.h> /* for error codes */ 

INT main (argc, argv) 

INT argc; 

CHAR *argv[] ; 

{ 

ULONG splerr ; 

ULONG cbBuf ; 

ULONG cTotal ; 

ULONG cReturned ; 

ULONG cbNeeded ; 

ULONG ulLevel; 

ULONG i ; 

PSZ pszComputerName ; 

PSZ pszQueueName ; 

PVOID pBuf = NULL; 

PPRJINF02 pprj2 ; 

/* Check that the comnand line entry was two parameters. */ 

if (argc 1= 2) 

{ 

printf ("Syntax: enumjob QueueName\n") ; 

DosExit( EXIT PROCESS , 0 ) ; 

} 


/* Either a NULL or a pointer to a NULL specify the local workstation. */ 
pszComputerName = (PSZ) NULL ; 

/* Set queue name equal to the value entered at the comnand line. */ 

pszQueueName = argv[l]; 

/* Valid level are 0 and2. Level 2 gives info for a PRJINF02 structure. */ 
ulLevel = 2L; 

/* Make the call the first time with cbBuf = zero so that we can get a */ 

/* return of the number of bytes that are need for pBuf to hold all of */ 

/* the information. The bytes needed will be returned in cbNeeded. */ 

splerr = SplEnumJob(pszComputerName, pszQueueName, ulLevel, pBuf.OL, 

&cReturned, &cTotal, 

ScbNeeded, NULL) ; 
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/* Check that the return code is one of the two valid errors at this time. */ 
if (splerr == ERR0R_M0RE_DATA || splerr = NERR_BufTooSmall ) 

{ 

/* Allocate memory for pBuf. ( No error checking is done on DosAllocMem */ 
/* call to keep this sample code simple.) */ 

DosAllocMem( SpBuf, cbNeeded, 

PAG_READ | PAGJIRITE | PAG_COMMIT ) ; 

/* Set bytes needed for buffer to the value returned by the first call. */ 
cbBuf = cbNeeded ; 

/* Make the call with all the valid information. */ 

SplEnumJob(pszComputerName,pszQueueName, ulLevel , 

pBuf, cbBuf, &cReturned,&cTotal , 

ScbNeeded.NULL ); 

/* Set up a pointer to point to the beginning of the buffer in which we */ 

/* have the returned information. 

pprj2=(PPRJINF02)pBuf; 


/* The number of structures in the buffer(pBuf) are returned in cReturned*/ 
/* Implement a for loop to print out the information for each structure. */ 
for (i=0; i<cReturned ;i++ ) 


{ 


printf ("Job ID = 
printf("Job Priority = 
printf ("User Name = 
printf("Position = 
printf ("Status = 
printf ("Submitted = 
printf("Size = 
printf("Comment = 
printf ("Document = 


%d\n", pprj2->uJobId); 

%d\n" , ppr j2->uPri ori ty) ; 
%s\n", pprj2->pszUserName) ; 
%d\n", pprj2->uPosition) ; 
%d\n", pprj2->fsStatus) ; 
%ld\n", pprj2->ul Submitted) ; 
%ld\n", pprj2->ulSize) ; 

%s\n" , pprj2->pszComment) ; 
%s\n\n" ,pprj2->pszDocument) ; 


/* Increment the pointer to point to the next structure in the buffer*/ 
pprj2++; 

} /* end for */ 

/* Free the memory that we allocated to make the call. */ 

DosFreeMem(pBuf) ; 

} 

else 

{ 

/* If any other error other than ERR0R_M0RE_DATA or NERR_BufTooSmall , 
then */ 

/* print the returned information. */ 

printf ("SplEnumJob Error=%ld, Total Jobs=%ld, Returned Jobs=%ld, Bytes 
Needed=%l d\n" , 

splerr, cTotal, cReturned, cbNeeded) ; 

} 

DosExit( EXIT_PROCESS , 0 ) ; 
return (splerr); 

} 
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#define INCL_SPL /* Or use INCL_PM */ 


SPLERR SplEnumPort (PSZ pszComputerName, ULONG ulLevel, PVOIO pBuf, ULONG cbBuf, 
PULONG pcReturned, PULONG pcTotal, PULONG pcbNeeded, 

PVOID pReserved) 


This function lists printer ports on the local workstation or on a remote server. 

Parameters 

pszComputerName (PSZ) - input 

Name of computer where queues are to be listed. 

A NULL string specifies the local workstation. 

ulLevel (ULONG) - input 
Level of detail. 

The level of detail required. This must be 0 or 1. 

pBuf (PVOID) - output 
Buffer. 

cbBuf (ULONG) - input 
Size, in bytes, of Buffer. 

pcReturned (PULONG) - output 
Number of entries returned. 

pcTotal (PULONG) - output 

Total number of entries available. 

pcbNeeded (PULONG) - output 

Size in bytes of available information. 

A value of 0 specifies that the size is not known. 

pReserved (PVOID) - output 
Reserved. 

This must be NULL. 


Returns 

NO_ERROR (0) 

ERROR ACCESS DENIED (5) 
ERROR_NOT_SUPPORTED (50) 
ERROR_BAD_NETPATH (53) 
ERROR_INVALID_PARAMETER (87) 
ERROR_INVALID_LEVEL (124) 
ERROR_MORE_DATA (234) 

N E R R Ne tNotS tart ed (2102) 
NERR_BufTooSmall (2123) 

NERR SpoolerNotLoaded (2161) 
NERRInvalidComputer (2351) 


No errors occurred. 

Access is denied. 

This request is not supported by the network. 
The network path cannot be located. 

An invalid parameter is specified. 

The level parameter is invalid. 

Additional data is available. 

The network program is not started. 

The API return buffer is too small. 

The spooler is not running. 

The computer name is invalid. 
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Remarks 

The buffer contents on return are: 

ulLevel Buffer Contents 

0 An array of PRPORTINFO structures 

1 An array of PRPORTINFOI structures 

Related Functions 

• SpICreateDevice 

• SpISetDevice 


Example Code 

This sample code will print out all the ports an associated Information. This is done at level 1, and 
for the local workstation. 

Idefine INCL_DOSMEMMGR 
Idefine INCL_SPL 
Idefine INCL_SPLDOSPRINT 

linclude <os2.h> 
linclude <stdio.h> 
linclude <neterr.h> 

INT main () 

{ 

SPLERR splerr ; 

ULONG cbBuf ; 

ULONG cTotal ; 

ULONG cReturned ; 

ULONG cbNeeded ; 

ULONG ulLevel = 1; 

ULONG i ; 

PSZ pszComputerName = NULL; 

PVOID pbuf ; 

PPRP0RTINF01 pPortl ; 

splerr = SplEnumPort(pszComputerName, ulLevel, pbuf, 0L, /* cbBuf */ 

&cReturned, &cTotal, 

ScbNeeded, NULL) ; 

if (splerr == ERR0R_M0RE_DATA || NERR_BufTooSmal 1 ) 

{ 

if (!DosAllocMem( &pbuf, cbNeeded, 

PAG_READ | PAGJIRITE | PAG_COMMIT) ) 

{ 

cbBuf = cbNeeded ; 

splerr = SplEnumPort(pszComputerName, ulLevel, pbuf, cbBuf, 

&cReturned, &cTotal, 

ScbNeeded, NULL) ; 

if (splerr == 0L) 

{ 

pPortl = ( PPRP0RTINF01) pbuf ; 
printf("Port names: "); 
for (i=0; i < cReturned; i++) 

{ 

printf(“Port - %s. Driver - %s Path - %s\n ", 

pPortl->pszPortName, pPortl->pszPortDri verName, 
pPortl->pszPortDri verPathName ) ; 
pPortl++ ; 

} 

printf("\n"); 

} 
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DosFreeMem(pbuf) ; 

} 

} 

else 

{ 

printf ("SplEnumPort splerr=%ld, \n",splerr) ; 

} 

DosExit( EXIT_PROCESS , 0 ) ; 
return (splerr); 

} /* end main */ 
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#define INCL_SPL /* Or use INCL_PM */ 

SPLERR SplEnumPrinter (PSZ pszComputerName, ULONG ulLevel, ULONG fIType, 

PVOID pBuf, ULONG cbBuf, PULONG pcReturned, PULONG pcTotal, 
PULONG pcbNeeded, PVOID pReserved) 

This function lists print destinations in the system. 

Parameters 

pszComputerName (PSZ) - input 

Name of computer where queues are to be listed. 

This must be NULL. 

ulLevel (ULONG) - input 
Level of detail required. 

This must be 0. 

fIType (ULONG) - input 

Type of print destinations required. 

SPL_PR_QUEUE Return only queues 

SPL_PR_DIRECT_DEVICE Return only direct print devices 

SPL_PR_QUEUED_DEVICE Return only queued print devices 

SPL_PR_LOCAL_ONLY Return only local print destinations 

pBuf (PVOID) - output 
Buffer. 

cbBuf (ULONG) - input 
Size, in bytes, of Buffer. 

pcReturned (PULONG) - output 
Number of entries returned. 

pcTotal (PULONG) - output 
Number of entries available. 

pcbNeeded (PULONG) - output 

Size in bytes of available information. 

A value of 0 specifies that the size is not known. 

pReserved (PVOID) - output 
Reserved. 

This must be NULL. 

Returns 

NO_ERROR (0) No errors occurred. 

ERROR_NOT_SUPPORTED (50) This request is not supported by the network. 
ERROR_INVALID_PARAMETER (87) An invalid parameter is specified. 

ERRORJNVALID LEVEL (124) The level parameter is invalid. 

ERROR_MORE_DATA (234) Additional data is available. 

NERR_NetNotStarted (2102) The network program is not started. 
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NERR_Bu<TooSmall (2123) The API return buffer is too small. 

NERR_SpoolerNotLoaded (2161) The spooler is not running. 

Remarks 

The buffer contents on return are: 

ulLevel Buffer Contents 

0 An array of PRINTERINFO structures. 

When the names of print destinations are returned, calls can be made to SpIQueryQueue or 
SpIQueryDevice to find out further information about the print destination. 


Related Functions 

• SpIQueryDevice 

• SpIQueryQueue 

Example Code 

This example code will print out all queues and printers for the local computer. It will print out both 
printers that are attached to a queue, and those that are direct printers. 

Idefine INCL_SPL 
Idefine INCL_SPLDOSPRINT 
linclude <os2.h> 

linclude <stdio.h> /* for printf function */ 

linclude <neterr.h> /* for error codes */ 

INT main () 

{ 

PVOID pBuf; 

ULONG fsType ; 

ULONG cbBuf ; 

ULONG cRes ; 

ULONG cTotal ; 

ULONG cbNeeded ; 

SPLERR splerr = 0 ; 

PPRINTERINFO pRes ; 

/* Set fsType to use all the flags. We will print out local device/queues.*/ 
fsType = SPL PR QUEUE | SPL PR DIRECT DEVICE | 

SPL_PR_QUEUED_DEVICE I SPL_PR_LOCAL_ONLY; 

/* Make function call with cbBuf equal to zero to get a return in cbNeeded*/ 

/* of the number of bytes needed for buffer to hold all the information */ 

splerr = SplEnumPrinter ( NULL.0 .fsType .NULL .NULL ,&cRes , 

ScTotal ,&cbNeeded .NULL ) ; 

/* The error return code will be one of the two following codes if */ 

/* all the parameters were correct. Otherwise it could be */ 

/* ERR0R_I NVALI D_PARAMETER . */ 

if ( splerr == ERR0R_M0RE_DATA || splerr == NERR_BufTooSmall ) 

{ 

/* Allocate memory for the buffer using the count of bytes that were */ 

/* returned in cbNeeded. For simplicity, no error checking is done. */ 
DosAllocMem( SpBuf, cbNeeded, 

PAG_READ| PAG_WRITE | PAG_COMMIT) ; 

/* Set count of bytes in buffer to value used to allocate buffer. */ 
cbBuf = cbNeeded; 
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/* Call function again with the correct buffer size. */ 

splerr = SplEnumPrinter ( NULL.0 .fsType ,pBuf .cbBuf ,&cRes , 

&cTotal ,&cbNeeded,NULL); 

/* If there are any returned structures in the buffer, then we will */ 
/* print out some of the information. */ 

if (cRes) 

{ 

pRes = (PPRINTERINFO)pBuf ; 
while ( cRes— ) 

{ 

/* Look at the flType element in the pRes structure to determine */ 
/* what type of print destination the structure represents. */ 
switch (pRes [cRes] .flType) 

{ 

case SPL_PR_QUEUE: 

printf("Print destination %s is a queue. \n", 
pRes[cRes] .pszPrintDestinationName) ; 
break; 

case SPL_PR_QUEUED_DEVICE: 

printf("Print destination %s is a queued printer. \n", 

pRes[cRes] .pszPrintDestinationName) ; 

break; 

case SPL_PR_DIRECT_DEVICE: 

printf("Print destination %s is a direct printer. \n", 
pRes[cRes] .pszPrintDestinationName) ; 

} 

printf ("Description - 

%s\n\n" , pRes [cRes] . pszDescri pti on) ; 

} 

} 

DosFreeMem(pBuf) ; 

} 

else 

{ 

/* If we had any other return code other than ERR0R_M0RE_DATA or */ 

/* NERR_BufTooSmall , we will print out the following information. */ 
printf ("SplEnumPrinter error= %ld \n", splerr); 

} 

DosExit( EXIT_PROCESS , 0 ) ; 
return (splerr); 
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#define INCL_SPL /* Or use INCL_PM */ 


SPLERR SplEnumQueue (PSZ pszComputerName, ULONG ulLevel, PVOID pBuf, 
ULONG cbBuf, PULONG pcReturned, PULONG pcTotal, 
PULONG pcbNeeded, PVOID pReserved) 


This function lists print queues on the local workstation or on a remote server, optionally supplying 
additional information. 

Parameters 

pszComputerName (PSZ) - input 

Name of computer where queues are to be listed. 

A NULL string specifies the local workstation. 

ulLevel (ULONG) - input 
Level of detail. 

The level of detail required. This must be 3, 4, 5 or 6. 

pBuf (PVOID) - output 
Buffer. 

cbBuf (ULONG) - input 
Size, in bytes, of Buffer. 

pcReturned (PULONG) - output 
Number of entries returned. 

pcTotal (PULONG) - output 

Total number of entries available. 

pcbNeeded (PULONG) - output 

Size in bytes of available information. 

A value of 0 specifies that the size is not known. 

pReserved (PVOID) - output 
Reserved. 

This must be NULL. 

Returns 

Return 

NO_ERROR (0) 

ERRORACCESSDENIED (5) 

ERROR NOT SUPPORTED (50) 

ERROR BAD NETPATH (53) 

ERROR JNVALID PARAMETER (87) 

ERROR JNVALID LEVEL (124) 

ERROR_MORE_DATA (234) 

N E R R Net Not S t ar ted (2102) 

NERR_BufTooSmall (2123) 

NERR_SpoolerNotLoaded (2161) 


No errors occurred. 

Access is denied. 

This request is not supported by the network. 
The network path cannot be located. 

An invalid parameter is specified. 

The level parameter is invalid. 

Additional data is available. 

The network program is not started. 

The API return buffer is too small. 

The spooler is not running. 
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NERRJnvalldComputer (2351) The computer name is invalid. 

Remarks 

The buffer contents on return are: 

ulLevel Buffer Contents 

3 An array of PRQINF03 structures 

4 An array of pcReturned PRQINF03 structures in which each PRQINF03 structure is 
followed by an array of PRJINF02 structures, one for each of job in the queue. cJobs in 
the PRQINF03 or PRQINF06 structure gives the number of jobs in the array. 

5 A queue name of type PSZ. 

6 An array of PRQINF06 structures 


Related Functions 

• SpIQueryJob 

• SpIQueryQueue 

• SpISetJob 

• SpISetQueue 

Example Code 

This sample code enumerates all the queues and the jobs in them that are on the local workstation. 

Idefine INCL_BASE 
Idefine INCL_SPL 
Idefine INCL_SPLDOSPRINT 
linclude <os2.h> 
linclude <stdio.h> 
linclude <neterr.h> 

INT main () 

{ 

SPLERR splerr; 

USHORT jobCount ; 

ULONG cbBuf ; 

ULONG cTotal ; 

ULONG cReturned ; 

ULONG cbNeeded ; 

ULONG ulLevel ; 

ULONG i , j ; 

PSZ pszComputerName ; 

PBYTE pBuf ; 

PPRQINF03 prq ; 

PPRJINF02 prj2 ; 

ulLevel = 4L; 

pszComputerName = (PSZ) NULL ; 

splerr = SplEnumQueue(pszComputerName, ulLevel, pBuf, 0L, /* cbBuf */ 

ScReturned, &cTotal , 

&cbNeeded, NULL) 

if ( splerr == ERR0R_M0RE_DATA || splerr == NERR_BufTooSmall ) 

{ 

if (!DosAllocMem( &pBuf, cbNeeded, 

PAG_READ | PAG_WRITE | PAG_COMMIT) 

) 

{ 

cbBuf = cbNeeded ; 

splerr = SplEnumQueue (pszComputerName, ulLevel, pBuf, cbBuf, 
fccReturned, ScTotal, 

ScbNeeded, NULL) 

if (splerr == N0_ERR0R) 

{ 
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/* Set pointer to point to the beginning of the buffer. */ 

prq = ( PPRQINF03) pBuf ; 


/* cReturned has the count of the number of PRQINF03 structures. */ 
for ( i =0 ; i < cReturned ; i++) 

{ 

printf( "Queue info: name - %s\n", prq->pszName) ; 

printf(" priority - %d starttime - %d endtime - %d fsType - 

%X\n" , 

prq->uPriority , prq->uStartTime , prq->uUnti1Time , 
prq->fsType ) ; 

printf(" pszSepFile - %s\n", prq->pszSepFile) ; 

printf(" pszPrProc - %s\n", prq->pszPrProc) ; 

printf (" pszParms - %s\n", prq->pszParms) ; 

printf (" pszComment - %s\n", prq->pszComment) ; 

printf(" pszPrinters - %s\n", prq->pszPrinters) ; 
printf (" pszDriverName- %s\n", prq->pszDri verName) ; 
if (prq->pDri verData) 

{ 

printf(“ pDri verData->cb - %ld\n", 

(ULONG)prq->pDri verData->cb) ; 

printf(" pDri verData->l Version - %ld\n", 

(ULONG) prq->pDri verData->l Vers ion) ; 
printf(" pDri verData->szDeviceName- %s\n", 
prq->pDri verData->szDevi ceName) ; 

} 

/* Save the count of jobs. There are this many PRJINF02 */ 

/* structures following the PRQINF03 structure. */ 

jobCount = prq->cJobs; 

printf("Job count in this queue is %d\n\n", jobCount); 

/* Increment the pointer past the PRQINF03 structure. */ 

prq++; 


/* Set a pointer to point to the first PRJINF02 structure. 

prj2=(PPRJINF02)prq; 

for (j=0;j < jobCount ; j++) 

{ 


printf("Job ID 
printf ("Job Priority 1 
printf("User Name 
printf("Position 
printf ("Status = 
printf ("Submitted 
printf("Size 
printf ("Comment 
printf ("Document 


%d\n", prj 2->uJobId) ; 

%d\n", prj2->uPriority) ; 
%s\n", prj2->pszUserName) ; 
%d\n", prj2->uPosition) ; 
%d\n", prj2->fsStatus) ; 
%ld\n", prj 2->ul Submitted) ; 
%ld\n" ,prj2->uiSize) ; 

%s\n", prj2->pszComment) ; 
%s\n\n",prj2->pszDocument) ; 


*/ 


/* Increment the pointer to point to the next structure. */ 
prj2++; 

} /* endfor jobCount */ 


/* After doing all the job structures, prj2 points to the next */ 
/* queue structure. Set the pointer for a PRQINF03 structure. */ 
prq = (PPRQINF03)prj2; 

}/*endfor cReturned */ 

} 

DosFreeMem(pBuf) ; 

} 

} /* end if Q level given */ 
else 
{ 

/* If we are here we had a bad error code. Print it and some other info.*/ 
printf ("SplEnumQueue Error=%ld, Total=%ld, Returned=%ld, Needed=%ld\n", 
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splerr, cTotal, cReturned, cbNeeded) 

} 

DosExit( EXIT_PROCESS , 0 ) ; 
return (splerr) ; 

} /* end main */ 
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#define INCL_SPL /* Or use INCL_PM */ 


SPLERR SplEnumQueueProcessor (PSZ pszComputerName, ULONG uiLevel, PVOID pBuf, 

ULONG cbBuf, PULONG pcReturned, PULONG pcTotal, 
PULONG pcbNeeded, PVOID pReserved) 


This function lists printer queue processors on the local workstation or on a remote server. 


Parameters 

pszComputerName (PSZ) - input 

Name of computer where queues are to be listed. 

A NULL string specifies the local workstation. 

uiLevel (ULONG) - input 
Level of detail. 

The level of detail required. This must be 0. 

pBuf (PVOID) - output 
Buffer. 

cbBuf (ULONG) - input 
Size, in bytes, of Buffer. 

pcReturned (PULONG) - output 
Number of entries returned. 

pcTotal (PULONG) - output 

Total number of entries available. 

pcbNeeded (PULONG) - output 

Size in bytes of available information. 

A value of 0 specifies that the size is not known. 

pReserved (PVOID) - output 
Reserved. 

This must be NULL. 


Returns 

NO_ERROR (0) 
ERRORACCESSDENIED (5) 
ERROR_NOT_SUPPORTED (50) 
ERROR_BAD_NETPATH (53) 
ERROR_INVALID_PARAMETER (87) 
ERROR_INVALID_LEVEL (124) 
ERROR_MORE_DATA (234) 
NERR_NetNotStarted (2102) 
NERR_BufTooSmall (2123) 
NERR_SpoolerNotLoaded (2161) 
NERRJnvalidComputer (2351) 


No errors occurred. 

Access is denied. 

This request is not supported by the network. 
The network path cannot be located. 

An invalid parameter is specified. 

The level parameter is invalid. 

Additional data is available. 

The network program is not started. 

The API return buffer is too small. 

The spooler is not running. 

The computer name is invalid. 
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Remarks 

The buffer contents on return are: 

ul Level Buffer Contents 

0 An array of PRQPROCINFO structures 

Related Functions 

• SpISetQueue 


Example Code 

This sample code enumerates and prints all the queue processors on the local computer. 

Idefine INCL_BASE 
Idefine INCL_SPL 
Idefine INCL_SPLDOSPRINT 

linclude <os2.h> 

linclude <stdio.h> /* for printf function */ 

linclude <neterr.h> /* for error codes */ 

INT main () 

{ 

SPLERR splerr ; 

ULONG cbBuf ; 

ULONG cTotal ; 

ULONG cReturned ; 

ULONG cbNeeded ; 

ULONG i ; 

PSZ pszComputerName = NULL ; 

PSZ pszQProcName ; 

PBYTE pBuf ; 

/* Call the function the first time with zero in cbBuf. The count 
/* of bytes needed for the buffer to hold all the info will be 
/* returned in cbNeeded. 

splerr = SplEnumQueueProcessor(pszComputerName, OL, NULL, OL, 

ScReturned, &cTotal , 

&cbNeeded,NULL ); 

/* If the return code is ERR0R_M0RE_DATA or NERR_BufTooSmall , */ 

/* then all the parameters were correct; and we can continue. */ 

if (splerr == ERR0R_M0RE_DATA || splerr == NERR_BufTooSmal 1 ) 

{ 

/* Allocate memory for the buffer to hold the returned information. Use */ 

/* the count of bytes that were returned by our first call. */ 

if (!DosAllocMem( &pbuf, cbNeeded, 

PAG_READ | PAG_WRITE | PAG_COMMIT ) ) 

{ 

/* Set count of bytes to the value returned by our first call. */ 

cbBuf = cbNeeded ; 

/* Now call the function a second time with the correct values, and */ 

/* the information will be returned in the buffer. */ 

splerr = SplEnumQueueProcessor (pszComputerName, OL, pBuf, cbBuf, 

ScReturned, ScTotal , 

&cbNeeded,NULL ) ; 

/* If we have no errors, then print out the buffer information. */ 
if (splerr == N0_ERR0R) 

{ 

/* Set a pointer to point to the beginning of the buffer. */ 

pszQProcName = (PSZ)pBuf; 


*/ 

*/ 

*/ 
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/* Print the names that are in the buffer. The count of the number*/ 
/* of names in pBuf have been returned in cReturned. */ 

for ( i =0 ; i < cReturned ; i++) 

{ 

printf( "Queue Processor name - %s\n", pszQProcName) ; 

/* Increment the pointer to point to the next name. */ 

pszQProcName += DRIV_NAME_SIZE + 1; 

} 

} 

/* Free the memory allocated for the buffer. */ 

DosFreeMem(pBuf) ; 

} 

} 

else 

{ 

/* If the first call to the function returned any other error code */ 

/* except ERR0R_M0RE_DATA or NERR_BufTooSmall , we print the */ 

/* following. */ 

printf( "SplEnumQueueProcessor error=%ld\n" .splerr ) ; 

} 

DosExit( EXIT_PR0CESS , 0 ) ; 
return (splerr); 
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#define INCL_SPL /* Or use INCL_PM */ 


SPLERR SplHoIdJob (PSZ pszComputerName, PSZ pszQueueName, ULONG ulJob) 


This function holds a job in a print queue. 

Parameters 

pszComputerName (PSZ) - input 

Name of computer where job is to be paused. 

A NULL string specifies the local workstation. 

pszQueueName (PSZ) - input 
Queue Name. 

ulJob (ULONG) - input 

Job identification number. 

Returns 

NO_ERROR (0) 

ERRORACCESSDENIED (5) 

ERRORNOTSUPPORTED (50) 

ERROR_BAD_NETPATH (53) 

N ER R_NetNotStarted (2102) 

NERR_JobNotFound (2151) 

NERR SpoolerNotLoaded (2161) 

NERR_JoblnvalldState (2164) 

NERR_lnvalldComputer (2351) 

Remarks 

If the job is already printing when the call is made, NERR_JoblnvalidState (2164) is returned. 

A user with administrator privilege can hold any job. 

A job created locally can be held locally regardless of user privilege level, but can be held remotely 
only by an administrator. 

A remote job can be held by a user without administrator privilege only if the username of the person 
initiating the request is the same as the username of the person who created the job. 

Related Functions 

• SplEnumJob 

• SpIQueryJob 

• SpIReleaseJob 


No errors occurred. 

Access is denied. 

This request is not supported by the network. 

The network path cannot be located. 

The network program is not installed. 

The print job does not exist. 

The spooler is not running. 

This operation cannot be performed on the print job in its 
current state. 

The computer name is invalid. 
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Example Code 

This sample code will hold the queue name that is entered at the prompt. 


Idefine INCL_BASE 
Idefine INCL_SPL 
linclude <os2.h> 
linclude <stdio.h> 
linclude <neterr.h> 
linclude <stdlib.h> 


/* for printf function */ 
/* for error codes */ 
/* for atoi function */ 


INT main (argc, argv) 

I NT argc; 

CHAR *argv[] ; 

{ 

SPLERR spierr ; 

PSZ pszComputerName = NULL ; 

PSZ pszQueueName = NULL ; 

ULONG ul Job ; 


/* Get job id from the input argument. */ 
ulJob = atoi (argv[l]) ; 

/* Cali the function to do the hold. If an error is returned, print it. */ 
spierr = SplHoldJob( pszComputerName, pszQueueName, ul Job) ; 

switch (spierr) 

{ 

case N0_ERR0R: 

printf ("Job %d was held.\n",ulJob) ; 
break; 

case NERR_JobNotFound: 

printf("Job does not exist. \n"); 
break; 

case NERR_JobInvalidState: 

printf("This operation can't be performed on the print Job.\n"); 
break; 
default: 

printf("Errorcode = %ld\n", spierr) ; 

} /* endswitch */ 

DosExit( EXIT_PROCESS , 0 ) ; 
argc; 

return (spierr); 
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#define INCL_SPL /* Or use INCL_PM */ 


SPLERR SplHoldQueue (PSZ pszComputerName, PSZ pszQueueName) 


This function holds a print queue. 


Parameters 

pszComputerName (PSZ) - input 

Name of computer where queue is to be paused. 

A NULL string specifies the local workstation. 

pszQueueName (PSZ) - input 
Queue name. 


Returns 

NO_ERROR (0) 

ERROR ACCESS DENIED (5) 
ERROR NOT SUPPORTED (50) 
ERROR_BAD_NETPATH (53) 
ERROR_INVALID_PARAMETER (87) 
N E R R NetNotStarted (2102) 
NERR_QNotFound (2150) 
NERR_SpoolerNotLoaded (2161) 
NERRJnvalldComputer (2351) 


No errors occurred. 

Access is denied. 

This request is not supported by the network. 
The network path cannot be located. 

An invalid parameter is specified. 

The network program is not started. 

The printer queue does not exist. 

The spooler is not running. 

The computer name is invalid. 


Remarks 

This function suspends processing of all print jobs except for a job currently printing. Print jobs can 
be submitted to a held queue, but no jobs will be spooled to a print destination or print processor 
until the queue is released by a SplHoldQueue call. 

To hold a remote queue requires administrator privilege on the remote server. 


Related Functions 

• SpICreateQueue 

* SplEnumQueue 

* SpIQueryQueue 

• SpIReleaseQueue 
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Example Code 

This sample code will hold the local queue name that is entered at the prompt. 

Idefine INCL_SPL 
linclude <os2.h> 

linclude <stdio.h> /* for printf function */ 

linclude <neterr.h> /* for error codes */ 

INT main (argc, argv) 

INT argc; 

CHAR *argv[] ; 

{ 

SPLERR splerr ; 

PSZ pszComputerName = NULL ; 

PSZ pszQueueName ; 

/* Get queue name from the input argument */ 
pszQueueName = argv[l]; 

/* Call the function to do the hold. If an error is returned, print it. */ 
splerr = SplHoldQueue(pszComputerName, pszQueueName); 
if (splerr != 0L) 

{ 

switch (splerr) 

{ 

case NERR_QNotFound: 

printf("Queue does not exist. \n" ) ; 
break; 

case NERR_SpoolerNotLoaded: 

printf("The Spooler is not running. \n") ; 
break; 
default: 

printf ("Errorcode = %ld\n", splerr); 

} /* endswitch */ 

} 

else 

{ 

printf ("Queue %s was held. \n", pszQueueName); 

} /* endif */ 

DosExit( EXIT_PROCESS , 0 ) ; 
argc; /* keep the compiler quiet */ 
return (splerr); 
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#define INCL_SPL /* Or use INCL_PM */ 


SPLERR SpIPurgeQueue (PSZ pszComputerName, PSZ pszQueueName) 


This function removes all jobs, except any currently printing, from a print queue. 

Parameters 

pszComputerName (PSZ) - input 

Name of computer where queue is to be purged. 

A NULL string specifies the local workstation. 

pszQueueName (PSZ) - input 
Queue name. 

Returns 

NO_ERROR (0) 

ERROR ACCESS DENIED (5) 

ERROR NOT SUPPORTED (50) 

ERROR_BAD_NETPATH (53) 

ERROR_INVALID_PARAMETER (87) 

N E RR_NetNotStarted (2102) 

NERR_QNotFound (2150) 

NERR_SpoolerNotLoaded (2161) 

NERRJnvalldComputer (2351) 

Remarks 

A print job that is printing is not affected by this function. 

If a print queue is pending deletion when this function is made, the queue is deleted when the job that 
is currently printing ends. 

To purge a remote queue requires administrator privilege on the remote server. 

Related Functions 

• SpiCreateQueue 

• SplEnumQueue 

• SpIQueryQueue 


No errors occurred. 

Access is denied. 

This request is not supported by the network. 
The network path cannot be located. 

An invalid parameter was specified. 

The network program is not started. 

The printer queue does not exist. 

The spooler is not running. 

The computer name is invalid. 
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Example Code 

This code will purge a local queue, whose name is entered at the prompt. 

Idefine INCL_SPL 
linclude <os2.h> 

linclude <stdio.h> /* for printf function */ 

linclude <neterr.h> /* for error codes */ 

INT main (argc, argv) 

INT argc; 

CHAR *arg[] ; 

{ 

SPLERR splerr ; 

PSZ pszComputerName = NULL ; 

PSZ pszQueueName ; 

/* Get queue name from the input argument. */ 

pszQueueName = arg[l]; 

/* Call the function to do the purge. If an error is returned, print it. */ 
spl err=Spl PurgeQueue (pszComputerName , pszQueueName) ; 
if (splerr != 0L) 

{ 

switch (splerr) 

{ 

case NERR_QNotFound: 

printf("Queue does not exist. \n"); 
break; 

case NERR_SpoolerNotLoaded: 

printf("The Spooler is not running. \n") ; 
break; 
default: 

printf("Errorcode = %ld\n”,splerr); 

} /* endswitch */ 

} 

else 

{ 

printf ("Queue %s was purged. \n", pszQueueName); 

} /* end if */ 

DosExit( EXIT_PROCESS , 0 ) ; 
return (splerr); 

} 
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#define INCL_SPL /* Or use INCL_PM */ 


BOOL SpIQmAbort (HSPL hspl) 


This function stops the generation of the spool file(s). It automatically closes the spool file (see 
SpIQmClose). 

Parameters 

hspl (HSPL) - input 
Spooler handle. 

Returns 

Success indicator: 

TRUE Successful completion 

FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRSPLQUEUEERROR 
PMERRSPLJNVHSPL 

Related Functions 

Prerequisite Functions 

• SpIQmOpen 

Other Related Functions 

• DevEscape 

Example Code 

This function is used to stop the generation of spool files and automatically close the spool file. 

Idefine INCL_SPL 
linclude <0S2.H> 

HSPL hspl; /* spooler handle. */ 

SpIQmAbort (hspl ) ; 


No spooler queue supplied or found. 
The spooler handle is invalid. 
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#define INCL_SPL /* Or use INCL_PM */ 


BOOL SpIQmAbortDoc (HSPL hspl) 


This function aborts a print job. 


Parameters 

hspl (HSPL) - input 
Spooler handle. 


Returns 

Success indicator: 

TRUE Successful completion 

FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRSPLQUEUEERROR No spooler queue supplied or found. 

PMERR_STARTDOC_NOT_ISSUED A request to write spooled output without first issuing a 

STARTDOC was attempted. 

PMERR_SPL_INV_HSPL The spooler handle is invalid. 

Remarks 

Everything that has been written to the spool file for this job since the last SpIQmStartDoc is erased, 
including the SpIQmStartDoc. 


Related Functions 

Prerequisite Functions 

• SpIQmOpen 

• SpIQmStartDoc 

Other Related Functions 

• DevEscape 


Example Code 

This function is used to abort a print job. Everything since the last SpIQmStartDoc is deleted. 

fdefine INCLJPL 
linclude <0S2.H> 

HSPL hspl; /* spooler handle. */ 

SpIQmAbortDoc (hspl ) ; 
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#define INCL_SPL /* Or use INCL_PM */ 


BOOL SpIQmClose (HSPL hspl) 


This function corresponds to the DevCIoseDC function: it closes the spool file. 

Parameters 

hspl (HSPL) - input 
Spooler handle. 

Returns 

Success indicator: 

TRUE Successful completion 

FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRSPLQUEUEERROR 
PMERR_ENDDOC_NOT ISSUED 

PMERR_SPL_INV_HSPL 

Related Functions 

Prerequisite Functions 

• SpIQmOpen 

Other Related Functions 

• DevCIoseDC 

Example Code 

This function is used to close a spool file that was opened with SpIQmOpen. 

Idefine INCL_SPL 
finclude <0S2.H> 

HSPL hspl; /* spooler handle. */ 

SplQmClose(hspl ) ; 


No spooler queue supplied or found. 

A request to close the spooled output without first issuing 
an ENDDOC was attempted. 

The spooler handle is invalid. 
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#define INCL_SPL /* Or use INCL_PM 7 


ULONG SpIQmEndDoc (HSPL hspl) 


This function corresponds to the DevEscape (DEVESC_ENDDOC) call: it ends a print job, and returns 
ulJob, a unique number to identify the job. 

Parameters 

hspl (HSPL) - input 
Spooler handle. 

Returns 

Job identifier: 

Nonzero Jobid (1 through 65 535) 

SPL.ERROR Error. 

Possible returns from WinGetLastError 

PMERRSPLQUEUEERROR 
PMERR_SPL_NO_DATA 
PMERR_SPL_INV_HSPL 

Remarks 

The print-job identifier is displayed to the user by the spooler while this job is on the queue, and 
while it is being printed. 

Related Functions 

Prerequisite Functions 

• SpIQmOpen 

• SpIQmStartDoc 

Other Related Functions 

• DevEscape 


No spooler queue supplied or found. 
No data supplied or found. 

The spooler handle is invalid. 
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Example Code 

This function is used to end a print job and return the job id. 

Idefine INCL_SPL 
linclude <0S2.H> 


HSPL hspl; /* spooler handle.. */ 
ULONG jobid; 

CHAR szMsg[100] ; 

HWND hwndClient; 


jobid = SplQmEndDoc(hspl); 


sprintf(szMsg, "ending job %d", jobid); 


Wi nMessageBox(HWND_DESKTOP , 
hwndClient, 
szMsg, 

"Printing Information", 

0 , 

MB_N0IC0N | MB_0K) ; 


/* client-window handle */ 
/* body of the message */ 
/* title of the message */ 
/* message box id */ 
/* icon and button flags */ 
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#define INCL_SPL /* Or use INCL_PM 7 


HSPL SpIQmOpen (PSZ pszToken, LONG ICount, PQMOPENDATA pqmdopData) 


This function corresponds to the DevOpenDC call: it opens a spool file for generating a print job. 


Parameters 

pszToken (PSZ) - input 

A token (nickname) that identifies spooler information. 

This information is held in the initialization file, and is the same as that in pqmdopData; any that 
is obtained from pqmdopData overrides the information obtained using pszToken. 

If pszToken is specified as then no device information is taken from the initialization file. 

Presentation Manager behaves as if is specified, but it allows any string to be specified. 

ICount (LONG) - input 
Number of items. 

This is the number of items present in the pqmdopData supplied. This can be shorter than the 
full list, if omitted items are irrelevant, or supplied from pszToken or elsewhere. 

pqmdopData (PQMOPENDATA) - input 
Open parameters. 


Returns 

Spooler handle: 

Nonzero Spooler handle 
SPLERROR Error. 

Possible returns from WinGetLastError 

PMERR INVALID PARM A parameter to the function contained invalid data. 

P M E R R_SPL IN V_LENGTH_OR_COUNT The length or count is invalid. 

PMERR_SPL_QUEUE_NOT_FOUND The spooler queue definition could not be found. 

PMERR_BASE_ERROR An OS/2 base error has occurred. The base error code 

can be accessed using the OffBinaryData field of the 
ERRINFO structure returned by WinGetErrorlnfo. 


Remarks 

None 

Related Functions 

• DevOpenDC 
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Example Code 

This sample code will initialize a PDEVOPENSTRUC and use it to call the function. 


Idefine INCL_SPL 
Idefine INCL_SPLDOSPRINT 
Idefine INCL_BASE 
Idefine INCL_ERRORS 

linclude <os2.h> 
linclude <stdio.h> 
linclude <stdlib.h> 


VOID main() 

{ 

HSPL hspl ; 

PDEVOPENSTRUC pdata; /* Pointer to a DEVOPENSTRUC structure */ 

PSZ pszToken = /* Spooler info identifier */ 


/* Allocate memory for pdata */ 
if ( !DosAllocMem( &pdata,sizeof( DEVOPENSTRUC ), 
(PAG_READ | PAG_WRITE | PAG_COMMIT ) ) 

{ 


/* Initialize elements 

pdata->pszLogAddress 

pdata->pszDri verName 

pdata->pdriv 

pdata->pszDataT ype 

pdata->pszComment 

pdata->pszQueueProcName 


of pdata */ 

= "LPT1Q1" ; 

= "IBMNULL"; 
= NULL; 

= " PM_Q_STD" ; 
= NULL; 

= NULL; 


pdata->pszQueueProcParams = NULL 
pdata->pszSpoolerParams = NULL 
pdata->pszNetworkParams = NULL 


hspl = SplQmOpen( pszToken, 4L, ( PQMOPENDATA )pdata ); 


if ( hspl != SPL_ERR0R ) /* Good spooler handle */ 

{ 

printf("SplQmOpen handle is %d\n",hspl); 

} 

else 

{ 

printf( "SpIQmOpen failed.\n"); 

} 

} 
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#define INCL_SPL /* Or use INCL_PM 7 


BOOL SpIQmStartDoc (HSPL hspl, PSZ pszDocName) 


This function corresponds to the DevEscape (DEVESC_STARTDOC) call; it starts a print job. 

Parameters 

hspl (HSPL) - input 
Spooler handle. 

pszDocName (PSZ) - input 
Document name. 

This is part of the job description which is displayed to the end user by the spooler. 

Returns 

Success indicator: 

TRUE Successful completion 

FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERRINVALIDPARM 
PMERRSPLQUEUEERROR 
PMERR_ENDDOC_NOT ISSUED 

PMERR_SPL_INV_HSPL 

Remarks 

This function signifies the start of a print job. It allows the application to specify a document name to 
be associated with the print job. 

Multiple print jobs can be generated, within a single queue manager open, by bracketing each job 
with SpIQmStartDoc and SpIQmEndDoc. 

Related Functions 

Prerequisite Functions 

• SpIQmOpen 

Other Related Functions 

• DevEscape 


A parameter to the function contained invalid data. 

No spooler queue supplied or found. 

A request to close the spooled output without first issuing 
an ENDDOC was attempted. 

The spooler handle is invalid. 
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Spooler File Start Document 


Example Code 

This function is used to start a print job. 

Idefine INCL_SPL 
linclude <0S2.H> 


HSPL hspl ; /* spooler handle. */ 
CHAR szDocName[] = "Test Job"; 
CHAR szMsg[100] ; 

HWND hwndClient; 


sprintf(szMsg, "Starting job named: %s" .szDocName) ; 
WinMessageBox(HWND_DESKTOP, 
hwndClient, 
szMsg, 

"Printing Information", 

0 , 

MB_N0IC0N | MB_0K) ; /* icon and button flags */ 


/* client-window handle */ 
/* body of the message */ 
/* title of the message */ 
/* message box id */ 


Spl QmStartDoc (hspl , szDocName) ; 
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#define INCL_SPL /* Or use INCL_PM 7 


BOOL SpIQmWrite (HSPL hspl, LONG ICount, PVOID pData) 


This function writes a buffer of data to the spool file for the print job. 

Parameters 

hspl (HSPL) - input 
Spooler handle. 

ICount (LONG) - input 
Length in bytes. 

This is the length of pData\ it must not be greater than 65 535. Data that is longer than this must 
be written by two or more calls. 

pData (PVOID) - input 

Buffer of data to be written to the spool file. 


Returns 

Success indicator: 

TRUE Successful completion 
FALSE Error occurred. 

Possible returns from WinGetLastError 

PMERR INVALID PARM A parameter to the function contained invalid data. 

PMERR_BASE_ERROR An OS/2 base error has occurred. The base error code 

can be accessed using the OffBinaryData field of the 
ERRINFO structure returned by WinGetErrorlnfo. 

PMERR_SPL_INV_LENGTH_OR_COUNT The length or count is invalid. 

PMERR_SPL_QUEUE_ERROR No spooler queue supplied or found. 

PMERR_SPL_PRINT_ABORT The job has already been aborted. 

PMERR_STARTDOC_NOT_ISSUED A request to write spooled output without first issuing a 

STARTDOC was attempted. 

P M E R R_SPL_C AN N OT_OP EN_FILE Unable to open the file. 

PMERR_SPL_INV_HSPL The spooler handle is invalid. 

PMERR_SPL_NO_DISK_SPACE There is not enough free disk space. 

Remarks 

None 

Related Functions 

Prerequisite Functions 

• SpIQmOpen 

• SpIQmStartDoc 
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Example Code 

This function writes a buffer of data to the spool file for the print job. 

Idefine INCL_SPL 
linclude <0S2.H> 

HSPL hspl; /* spooler handle. */ 

SplQmWrite(hspl , 

sizeof("DATA") , 

(PVOID) "DATA") ; 
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Spooler Query Device 


#define INCLSPL /* Or use INCL_PM 7 


SPLERR SpIQueryDevice (PSZ pszComputerName, PSZ pszPrlntDevIceName, ULONG ulLevel, 

PVOID pBuf, ULONG cbBuf, PULONG pcbNeeded) 


This function retrieves information about a print device. 


Parameters 

pszComputerName (PSZ) - input 

Name of computer where print device is to be queried. 

A NULL string specifies the local workstation. 

pszPrlntDevIceName (PSZ) - input 
Name of Print Device. 

This can specify a print device name or a port name. If ulLevel is 0, it must be a port name. If 
ulLevel is 2 or 3 , it must be a print device name. 

ulLevel (ULONG) - input 
Level of detail required. 

This must be 0, 2 or 3. 

pBuf (PVOID) - output 
Buffer. 

cbBuf (ULONG) - input 
Size, in bytes, of Buffer. 

pcbNeeded (PULONG) - output 

Size in bytes of available information. 


Returns 

NO_ERROR (0) 

ERRORNOTSUPPORTED (50) 
ERROR_BAD_NETPATH (53) 
ERROR_INVALID_PARAMETER (87) 
ERROR_INVALID_LEVEL (124) 
ERROR_MORE_DATA (234) 

N ER R_NetNotStarted (2102) 
NERR_BufTooSmall (2123) 
NERR_DestNotFound (2152) 
NERR_SpoolerNotLoaded (2161) 
NERRJnvalldComputer (2351) 


No errors occurred. 

This request is not supported by the network. 
The network path cannot be located. 

An invalid parameter is specified. 

The level parameter is invalid. 

Additional data is available. 

The network program is not started. 

The API return buffer is too small. 

The print device cannot be found. 

The spooler is not running. 

The computer name is invalid. 
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Spooler Query Device 


Remarks 

The buffer contents on return are: 

ulLevel Buffer Contents 

0 A port name. 

2 A print device name, of type PSZ. 

3 A PRDINF03 structure. 

If ulLevel is 3, and pBuf cannot hold the entire PRDINF03 structure, SpIQueryDevice returns 
NERR_BufTooSmall (2123). 

T o obtain the size of buffer required, call SpIQueryDevice with the required value of ulLevel and a 
NULL buffer. The number of bytes required is returned in pcbNeeded. 

If no job is printing on the print device, bits 2-11 of fsStatus in the PRDINF03 data structure are 
meaningless. 


Related Functions 

• SpICreateDevice 

• SpIDeleteDevice 

• SplEnumDevice 


Example Code 

This sample code returns information for the device name that is entered at the command line. The 
local workstation is selected. The query is done for level 3 information. 

Idefine INCL_BASE 
Idefine INCL_DOSMEMMGR 
Idefine INCL_SPL 
Idefine INCL_SPLDOSPRINT 

linclude <os2.h> 
linclude <stdio.h> 
linclude <neterr.h> 

INT main (argc, argv) 

I NT argc; 

CHAR *argv[] ; 

{ 

SPLERR splerr ; 

ULONG cbBuf; 

ULONG cbNeeded ; 

ULONG ulLevel ; 

PSZ pszComputerName ; 

PSZ pszPrintDeviceName ; 

PVOID pBuf ; 

PPRDINF03 pprd3 ; 

if (argc != 2) 

{ 

printf (“Syntax: sdqry DeviceName \n"); 

DosExit( EXIT_PROCESS , 0 ) ; 

} 

pszComputerName = (PSZ) NULL ; 
pszPrintDeviceName = argv[l]; 
ulLevel = 3; 

splerr = SplQueryDevice(pszComputerName, pszPrintDeviceName, 
ulLevel, (PVOID)NULL, 0L, ScbNeeded ); 
if (splerr != NERR_BufTooSmall ) 

{ 
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printf ("SpIQueryDevice Err=%ld, cbNeeded=%ld\n",splerr, cbNeeded) ; 
DosExit( EXIT_PROCESS , 0 ) ; 

} 

if (!DosAllocMem( &pBuf, cbNeeded, 

PAG_READ | PAG_WRITE | PAG_COMMIT) ) { 
cbBuf= cbNeeded ; 

splerr = SplQueryDevice(pszComputerName, pszPrintDeviceName, 
ul Level, pBuf, cbBuf, &cbNeeded) ; 

printf ("SpIQueryDevice Error=%ld, Bytes Needed=%ld\n", splerr, 
cbNeeded) ; 


pprd3=(PPRDINF03)pBuf; 
printf ("Print Device info: name 


printf (“User Name = %s\n", 
printf("Logical Address= %s\n", 
printf("Job ID = %d\n"„ 
printf ("Status = %d\n", 
printf ("Status Comment = %s\n", 
printf (“Comment = %s\n", 
printf("Drivers = %s\n", 
printf ("Time = %d\n", 
printf ("Time Out = %d\n", 
DosFreeMem(pBuf) ; 

} 


DosExit( EXIT_PROCESS , 0 ) ; 
return (splerr): 


- %s\n", pprd3->pszPrinterName) ; 
pprd3->pszUserName) ; 
pprd3->pszLogAddr) ; 
pprd3->uJobId) ; 
pprd3->fsStatus) ; 
pprd3->pszStatus) ; 
pprd3->pszComment) ; 
pprd3->pszDrivers) ; 
pprd3->time) ; 
pprd3->usTime0ut) ; 
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Spooler Query Job 


#define INCL_SPL /* Or use INCL_PM */ 


SPLERR SpIQueryJob (PSZ pszComputerName, PSZ pszQueueName, ULONG ulJob, 

ULONG ulLevel, PVOID pBuf, ULONG cbBuf, PULONG pcbNeeded) 


This function retrieves information about a print job. 

Parameters 

pszComputerName (PSZ) - input 

Name of computer where print job is to be queried. 

A NULL string specifies the local workstation. 

pszQueueName (PSZ) - input 
Queue Name. 

ulJob (ULONG) - input 

Job identification number. 

ulLevel (ULONG) - input 
Level of detail required. 

This must be 0, 2, or 3. 

pBuf (PVOID) - output 
Buffer. 

cbBuf (ULONG) - input 
Size, in bytes, of Buffer. 

pcbNeeded (PULONG) - output 

Size in bytes of available information. 


Returns 

NO_ERROR (0) 
ERRORACCESSDENIED (5) 
ERROR NOT SUPPORTED (50) 
ERROR_BAD_NETPATH (53) 

ERROR JNVALID_PARAMETER (87) 
ERROR _INVALID_LEVEL (124) 
ERROR_MORE_DATA (234) 
NERR_NetNotStarted (2102) 
NERRBufTooSmall (2123) 
NERR_JobNotFound (2151) 
NERR_SpoolerNotLoaded (2161) 
NERRJnvalldComputer (2351) 


No errors occurred. 

Access is denied. 

This request is not supported by the network. 
The network path cannot be located. 

An invalid parameter is specified. 

The level parameter is invalid. 

Additional data is available. 

The network program is not started. 

The API return buffer is too small. 

The print job does not exist. 

The spooler is not running. 

The computer name is invalid. 
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Remarks 

The buffer contents on return are: 

ulLevel Buffer Contents 

0 The job identifier 

2 A PRJINF02 structure, with variable information, up to the cbBuf of pBuf 

3 A PRJINF03 structure, with variable information, up to the cbBuf of pBuf. 

Related Functions 

• SplEnumJob 

• SplEnumQueue 

• SpIQueryQueue 

• SpISetJob 

Example Code 

The following sample code will print out the information contained in a PRJINF03 structure that is 
returned from a SpIQueryJob call. The parameters that are entered on the command line are the 
computer name, queue name, and the job id. 

Idefine INCL_SPL 
Idefine INCL_SPLDOSPRINT 
linclude <os2.h> 

linclude <stdio.h> /* for printf call */ 

linclude <stdlib.h> /* for atoi call */ 

linclude <neterr.h> /* for error codes */ 

INT main (argc, argv) 

INT argc; 

CHAR *argv [] ; 

{ 

INT splerr; 

ULONG cbBuf ; 

ULONG cbNeeded ; 

ULONG ulLevel ; 

ULONG ul Job ; 

PSZ pszComputerName ; 

PSZ pszQueueName ; 

PVOID pBuf; 

PPRJINF03 pprj3 ; 

/* Input the parameters Computer Name, Queue Name, and Job ID. Check that */ 

/* three parameters have been entered along with the program name. */ 

if (argc != 4) 

{ 

/* Print a message and exit if wrong number of parameters entered */ 
printf ("Syntax: sjqry ComputerName QueueName JobID \n"); 

DosExit( EXIT_PROCESS , 0 ) ; 

} 

/* Set the parameters to the values entered on the command line. */ 

pszComputerName = argv[l] ; 
pszQueueName = argv [2] ; 
ulJob = atoi (argv[3]); 

/* Valid levels are 0,2, and 3. Level 3 returns a PRJINF03 structure. */ 
ulLevel = 3 ; 

/* Call the function with cbBuf equal to zero in order to get the number */ 

/* of bytes needed returned in cbNeeded. */ 

splerr = SpIQueryJob (pszComputerName, pszQueueName, ulJob, 

ulLevel, (PVOID)NULL, 0L, &cbNeeded ); 
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) 


/* Only continue if the error return code is one of the two following, 
if (splerr == NERR_BufTooSmal 1 || splerr == ERR0R_M0RE_DATA ) 

{ 

/* Allocate memory for the buffer(pBuf) . Only continue if memory is 
/* successfully allocated, 
if (DosAllocMem( &pBuf, cbNeeded, 

PAG_READ | PAG_WRITE | PAG_COMMIT) 


/* Set the count of bytes needed for the buffer to the value 
/* returned in cbNeeded from the first call. 
cbBuf = cbNeeded ; 


*/ 

*/ 

*/ 


*/ 

*/ 


/* Make the call again with all the correct values. */ 

Spl QueryJob(pszComputerName , pszQueueName , ul Job, 

ul Level, pBuf, cbBuf, ScbNeeded) ; 


/* Set a pointer to point to the beginning of the buffer that holds */ 
/* the returned structure. */ 
pprj3=(PPRJINF03)pBuf; 


/* Print out the information 
printf("Job ID = %d\n", 
printf("Job Priority 3 %d\n", 
printf ("User Name = %s\n", 
printf( "Posit ion = %d\n", 
printf ("Status = %d\n", 
printf ("Submitted = %ld\n" 
printf(“Size = %ld\n" 
printf ("Comment = %s\n", 
printf ("Document = %s\n", 
printf ("Notify Name = %s\n", 
printf ("Data Type = %s\n“, 
printf("Parms = %s\n", 
printf ("Status = %s\n", 
printf ("Dueue = %s\n", 
printf ("QProc Name = %s\n", 
printf("QProc Parms = %s\n“, 
printf ("Driver Name = %s\n", 
printf ("Printer Name= %s\n". 


for each element in the structure. 
pprj3->uJobId); 
pprj3->uPriority) ; 
pprj3->pszUserName) ; 
pprj3->uPosition); 
pprj3->fsStatus) ; 

,pprj3->ul Submitted) ; 
,pprj3->ulSize); 
pprj3->pszComment) ; 
ppr j3->pszDocument) ; 
ppr j3->pszNoti fyName) ; 
pprj3->pszDataType) ; 
pprj3->pszParms) ; 
pprj3->pszStatus) ; 
pprj3->pszDueue) ; 
pprj3->pszQProcName) ; 
pprj3->pszQProcParms) ; 
ppr j3->pszDri verName) ; 
pprj3->pszPrinterName) ; 


/* If pDriverData is NULL, then we can not access any data. */ 

if (pprj3->pDriverData) 

{ 

printf(" pDriverData->cb - %ld\n", 

(UL0NG)pprj3->pDriverData->cb) ; 
printf(" pDriverData->l Version - %ld\n", 

(U LONG) ppr j3->pDri verData->l Vers i on) ; 
printf(" pDriverData->szDeviceName - %s\n", 

pprj3->pDr i verData->szDevi ceName) ; 

} 

printf ("/n") ; 
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/* Free memory that we allocated. */ 

DosFreeMem(pBuf) ; 

} 

} 

else 

{ 

/* If we are here than we have an error code. Print it out. */ 

printf(" SpIQueryJob Error=%ld, Bytes Needed=%ld\n",splerr, cbNeeded); 

} 

DosExit( EXIT_PROCESS , 0 ) ; 
return (spl err) ; 
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#define INCL_SPL /* Or use INCL_PM */ 


SPLERR SpIQueryQueue (PSZ pszComputerName, PSZ pszQueueName, ULONG ulLevel, 
PVOID pBuf, ULONG cbBuf, PULONG pcbNeeded) 


This function supplies information about a print queue, and, optionally, about the jobs in it. 

Parameters 

- pszComputerName (PSZ) - input 

Name of computer where queue is to be queried. 

A NULL string specifies the local workstation. 

pszQueueName (PSZ) - input 
Queue name. 

ulLevel (ULONG) - input 
Level of detail required. 

This must be 3, 4, 5 or 6. 

pBuf (PVOID) - input 
Buffer. 

cbBuf (ULONG) - input 
Size, in bytes, of Buffer. 

pcbNeeded (PULONG) - output 

Size in bytes of available information. 


Returns 

Return 

NO_ERROR (0) 
ERRORACCESSDENIED (5) 
ERROR NOT SUPPORTED (50) 
ERROR_BAD_NETPATH (53) 
ERROR_INVALID_PARAMETER (87) 
ERROR_INVALID_LEVEL (124) 
ERROR_MORE_DATA (234) 
NERR_NetNotStarted (2102) 
NERR_BufTooSmall (2123) 
NERR_QNotFound (2150) 
NERR_SpoolerNotLoaded (2161) 
NERR_lnvalldComputer (2351) 


No errors occurred. 

Access is denied. 

This request is not supported by the network. 
The network path cannot be located. 

An invalid parameter is specified. 

The level parameter is invalid. 

Additional data is available. 

The network program is not started. 

The API return buffer is too small. 

The printer queue does not exist. 

The spooler is not running. 

The computer name is invalid. 
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Remarks 

The buffer contents on return are: 
ulLevel Buffer Contents 

3 A PRQINF03 structure, with associated variable information up to cbBuf. 

4 A PRQINF03 structure, with associated variable information, and an array of 
PRJINF02 structures, one for each job in the queue, up to cbBuf. 

5 A queue name of type PSZ. 

6 A PRQINF06 structure, with associated variable information up to cbBuf. 

If ulLevel is 3 or 4, and pBuf cannot hold the entire PRQINF03 structure, SpIQueryQueue returns 
NERR_BufTooSmall (2123). If ulLevel is 6, and pBuf cannot hold the entire PRQINF06 structure, 
SpIQueryQueue returns NERR_BufTooSmall (2123). 

If ulLevel is 4, and pBuf cannot hold all the available PRJINF02 structures, SpIQueryQueue returns 
ERROR_MORE_DATA (234). 

To obtain the size of buffer required, call SpIQueryQueue with the required value of ulLevel and a 
NULL buffer. The number of bytes required is returned in pcbNeeded. 


Related Functions 

• SplEnumQueue 

• SpIQueryJob 

• SpISetJob 

• SpISetQueue 

Example Code 

This sample code queries the local workstation for a queue name that is entered at the command 
prompt. The query is done at level 4 which returns returns in the buffer information in a PRQINF03 
structure and follows this with PRJINF02 structures - one for each job in the queue. 

fdefine INCL_SPL 
fdefine INCL_SPLDOSPRINT 

finclude <os2.h> 
finclude <stdio.h> 
finclude <neterr.h> 


main (argc, argv) 

INT argc; 

CHAR * 

argv[] ; 

ULONG 

splerr ; 

ULONG 

cbBuf; 

ULONG 

cbNeeded ; 

ULONG 

ul Level ; 

ULONG 

i ; 

USHORT 

uJobCount ; 

PSZ 

pszComputerName 

PSZ 

pszQueueName ; 

PVOID 

pBuf; 

PPRJINF02 prj2 ; 
PPRQINF03 prq3 ; 


if (argc != 2) 

{ 

printf ("Syntax: setqryq QueueName \n") ; 
DosExit( EXIT_PROCESS , 0 ) ; 


pszComputerName = (PSZ) NULL ; 
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pszQueueName = argv[l]; 
ul Level = 4L; 

splerr = SpIQueryQueue (pszComputerName, pszQueueName, ul Level, 

(PVOID)NULL, 0L, &cbNeeded ); 

if (splerr != NERR_BufTooSmal 1 || splerr != ERR0R_M0RE_DATA ) 

{ 

printf(“SplQueryQueue Error=%ld, cbNeeded=%ld\n", splerr, cbNeeded) ; 
DosExit( EXIT_PROCESS , 0 ) ; 

} 

if (!DosAllocMem( +pBuf, cbNeeded, 

PAG_READ | PAG_WRITE | PAG_COMMIT) 

{ 

cbBuf = cbNeeded ; 

splerr = SplQueryQueue(pszComputerName, pszQueueName, ulLevel, 

pBuf, cbBuf, &cbNeeded) ; 

prq3=(PPRQINF03)pBuf; 

printf("Queue info: name- %s\n", prq3->pszName) ; 
printf (“ priority - %d starttime - %d endtime - %d fsType - %X\n" , 
prq3->uPriority , prq3->uStartTime , prq3->uUntilTime , 
prq3->fsType ) ; 

printf(" pszSepFile - %s\n", prq3->pszSepFile) ; 

printf(" pszPrProc - %s\n", prq3->pszPrProc) ; 

printf (" pszParms - %s\n", prq3->pszParms) ; 

printf(" pszComment - %s\n", prq3->pszComment) ; 

printf(" pszPrinters - %s\n", prq3->pszPrinters) ; 
printf(" pszDriverName - %s\n", prq3->pszDriverName) ; 
if (prq3->pDriverData) 

{ 

printf (" pDriverData->cb - %ld\n", 

(UL0NG)prq3->pDriverData->cb); 
printf(" pDriverOata->l Vers ion - %ld\n“, 

(ULONG) prq3->pDri verData->l Vers ion) ; 
printfC pDriverData->szDeviceName - %s\n", 

prq3->pDri verData->szDevi ceName) ; 

} 

/* Store the job count for use later in the for loop. */ 

uJobCount = prq3->cJobs; 

printf("Job count in this queue is %d\n\n”, uJobCount); 

/* Increment the pointer to the PRQINF03 structure so that it points to*/ 
/* the first structure after itself. */ 

prq3++; 


/* Cast the prq3 pointer to point to a 
/* pointer to point to that place. 
prj2=(PPRJINF02)prq3; 
for (i=0 ; i<uJobCount ;i++ ) 
printf("Job ID = %d\n", 
printf("Priority = %d\n“, 
printf ("User Name = %s\n", 
printf (“Position = %d\n", 
printf("Status = %d\n", 
printf ("Submitted = %ld\n" 
printf("Size = %ld\n" 
printf ("Comment = %s\n", 
printf("Document = %s\n\n 


PRJINF02 structure, and set a 


{ 

prj2->uJobId); 
prj2->uPriority) ; 
prj2->pszUserName) ; 
prj2->uPosition); 
prj2->fsStatus) ; 
prj2->ul Submitted) ; 
prj2->ul Size) ; 
prj2->pszConment) ; 

1 ,prj2->pszDocument) ; 


*/ 

*/ 
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/* Increment the pointer to point to the next structure. */ 

prj2++; 

} /* end for */ 

DosFreeMem(pBuf) ; 

} 

DosExit( EXIT_PROCESS , 0 ) ; 
return (splerr); 

} 
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#define INCL_SPL /* Or use INCL_PM */ 


SPLERR SpIReleaseJob (PSZ pszComputerName, PSZ pszQueueName, ULONG ulJob) 


This function releases a held print job. 

Parameters 

pszComputerName (PSZ) - input 

Name of computer where job is to be continued. 

A NULL string specifies the local workstation. 

pszQueueName (PSZ) - input 
Queue Name. 

ulJob (ULONG) - input 

Job identification number. 

Returns 

NO_ERROR (0) 

ERROR ACCESS DENIED (5) 

ERROR_NOT_SUPPORTED (50) 

ERROR_BAD_NETPATH (53) 

N E R RNetNot Started (2102) 

NERR_JobNotFound (2151) 

NERR_SpoolerNotLoaded (2161) 

NERR_JoblnvalldState (2164) 

NERR_lnvalldComputer (2351) 

Remarks 

Any job can be released by a user with administrator privilege. 

A job created locally can be released locally regardless of user privilege level, but it can be released 
remotely only by a user with administrator privilege. 

A remote job can be released by a user without administrator privilege only if the user identification 
of the person initiating the request is the same as the user identification of the person who created 
the job. 

Related Functions 

• SplEnumJob 

• SplHoIdJob 

• SpIQueryJob 


No errors occurred. 

Access is denied. 

This request is not supported by the network. 

The network path cannot be located. 

The network program is not started. 

The print job does not exist. 

The spooler is not running. 

This operation cannot be performed on the print job in its 
current state. 

The computer name is invalid. 
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Example Code 

This sample code will release the job id that is entered at the prompt. 

Idefine INCL_BASE 
Idefine INCL_SPL 
linclude <os2.h> 

linclude <stdio.h> /* for printf function */ 

linclude <stdlib.h> /* for atoi function */ 

linclude <neterr.h> /* for error codes */ 

INT main (argc, argv) 

I NT argc; 

CHAR *argv[]; 

{ 

SPLERR splerr ; 

ULONG ul Job ; 

PSZ pszComputerName = NULL ; 

PSZ pszQueueName = NULL ; 

/* Get job id from the input argument */ 
ulJob = atoi (argv[l]) ; 

/* Call the function to do the release. If an error is returned, print it. */ 
splerr=SplReleaseJob( pszComputerName, pszQueueName, ulJob); 
switch (splerr) 

{ 

case NO ERROR: 

printf("Job %d was rel eased. \n“, ulJob); 
break; 

case NERR_JobNotFound: 

printf("Job does not exist. \n"); 
break; 

case NERR_JobInvalidState: 

printf(“This operation can't be performed on the print Job.\n"); 
break; 
default: 

printf("Errorcode = %ld\n", splerr) ; 

} /* endswitch */ 

DosExit( EXIT_PROCESS , 0 ) ; 
argc; 

return (splerr); 
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#define INCL_SPL /* Or use INCL_PM */ 


SPLERR SpIReleaseQueue (PSZ pszComputerName, PSZ pszQueueName) 


This function releases a held print queue. 

Parameters 

pszComputerName (PSZ) - input 

Name of computer where queue is to be continued. 

A NULL string specifies the local workstation. 

pszQueueName (PSZ) - input 
Queue name. 

Returns 

NO_ERROR (0) 

ERROR ACCESS DENIED (5) 

ERROR NOT SUPPORTED (50) 

ERROR_BAD_NETPATH (53) 

NE R R_NetNotStarted (2102) 

NERR_QNotFound (2150) 

NERR_SpoolerNotLoaded (2161) 

NERRJnvalidComputer (2351) 

Remarks 

This function releases a queue that has been held by a SplHoldQueue function, or disabled by an 
error on the queue. It does not affect an active print queue. 

To release a queue on a remote server requires administrator privilege on the remote server. 

Related Functions 

• SplEnumQueue 

• SplHoldQueue 

• SpIQueryQueue 


No errors occurred. 

Access is denied. 

This request is not supported by the network. 
The network path cannot be located. 

The network program is not started. 

The printer queue does not exist. 

The spooler is not running. 

The computer name is invalid. 
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Example Code 

This sample code will release the local queue that is entered at the prompt. 

fdefine INCL_SPL 
#inc1ude <os2.h> 

linclude <stdio.h> /* for printf function */ 

linclude <neterr.h> /* for error codes */ 

INT main (argc, argv) 

INT argc; 

CHAR *argv[] ; 

{ 

SPLERR splerr ; 

PSZ pszComputerName = NULL ; 

PSZ pszQueueName ; 

/* Get queue name from the input argument. */ 

pszQueueName = argv[l]; 

/* Call the function to do the release. If an error is returned, print it. */ 
splerr=SplReleaseQueue(pszComputerName, pszQueueName) ; 
if (splerr != 0L) 

{ 

switch (splerr) 

{ 

case NERR_QNotFound : 

printf("Queue does not exist. \n"); 
break; 

case NERR_SpoolerNotLoaded: 

printf ("The Spooler is not running. \n") ; 
break; 
default: 

printf ("Errorcode = %ld\n", splerr); 

} /* endswitch */ 

} 

else 

{ 

printf("Queue %s was released. \n" .pszQueueName) ; 

} /* end if */ 

DosExit( EXIT_PROCESS , 0 ) ; 
return (splerr); 
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#define INCL_SPL /* Or use INCL_PM */ 


SPLERR SpISetDevice (PSZ pszComputerName, PSZ pszPrlntDevIceName, ULONG ulLevel, 
PVOID pBuf, ULONG cbBuf, ULONG ulParmNum) 


This function modifies the configuration of a print device. 


Parameters 

pszComputerName (PSZ) - input 

Name of computer where print device is to be modified. 

A NULL string specifies the local workstation. 

pszPrlntDevIceName (PSZ) - input 
Name of Print Device. 

ulLevel (ULONG) — input 
Level of detail required. 

This must be 3. 

pBuf (PVOID) - input 
Buffer. 

cbBuf (ULONG) - input 
Size, in bytes, of Buffer. 

ulParmNum (ULONG) - input 
Parameter number. 


Specifies either that the entire PRDINF03 structure is to be modified, or that one specific 
parameter only is to be modified. If ulParmNum is 0, pBuf must contain a complete PRDINF03 
structure. Otherwise, pBuf must contain a valid value corresponding to the parameter to be 
modified: 


Parameter 

pszLogAddr 

pszComment 

pszDrivers 

usTimeOut 


Constant (Value) 

PRD_LOGADDR_PARMNUM (3) 
PRD_COMMENT_PARMNUM (7) 
PRD_DRIVERS_PARMNUM (8) 
PRD_TIMEOUT_PARMNUM (10) 


Returns 

NO_ERROR (0) 
ERRORACCESSDENIED (5) 
ERROR_NOT_SUPPORTED (50) 
ERROR_BAD_NETPATH (53) 
ERROR_INVALID_PARAMETER (87) 
ERROR_INVALID_LEVEL (124) 
NERR_NetNotStarted (2102) 
NERR_BufTooSmall (2123) 
NERR_DestNotFound (2152) 
NERR_SpoolerNotLoaded (2161) 
NERR_DestlnvalldState (2162) 


No errors occurred. 

Access is denied. 

This request is not supported by the network. 

The network path cannot be located. 

An invalid parameter is specified. 

The level parameter is invalid. 

The network program is not started. 

The API return buffer is too small. 

The print device cannot be found. 

The spooler is not running. 

This operation cannot be performed on the print device. 
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NERR_SpoolNoMemory (2165) 
NERR_DrlverNotFound (2166) 
NERR_BadDev (2341) 
NERRJnvalldCompuler (2351) 


A spooler memory allocation failure occurred. 
The device driver does not exist. 

The requested device is invalid. 

The computer name is invalid. 


Remarks 

This function allows modification of a print device and its connection to a logical address. To 
disconnect a print device from a port, use ulLevel= 3, ulParmNum=3, and pBuf is a NULL string. 

To modify a print device on a remote server requires administrator privilege. 


Related Functions 

• SplEnumDevice 

• SplEnumDriver 

• SplEnumPort 

• SplEnumPrinter 

• SpIQueryDevice 

Example Code 

This sample code first gets a device name from the command line. It then prompts the user for a 
parameter number and a value associated with it. 

Idefine INCLJASE 
Idefine INCL_DOSMEMMGR 
Idefine INCLJPL 
Idefine INCL_SPLDOSPRINT 
linclude <os2.h> 
linclude <stdio.h> 
linclude <string.h> 
linclude <stdlib.h> 
linclude <neterr.h> 

INT main (argc, argv) 

INT argc; 

CHAR *argv[] ; 

{ 

CHAR bufValue[2]={0}; 

CHAR buflnput[128]={0}; 

ULONG splerr ; 

ULONG cbBuf ; 

ULONG ul ParmNum ; 

USHORT usParm; 

PSZ pszComputerName ; 

PSZ pszPrintDeviceName ; 

PVOID pBuf; 

if (argc != 2) 

{ 

printf("Syntax: sdset DeviceName \n"); 

DosExit( EXIT_PROCESS , 0 ) ; 

} 

pszComputerName = (PSZ) NULL ; 

/* Set the print device name to the value from the command line. */ 
pszPrintDeviceName = argv[l]; 

/* Get the parameter and the value. Store them in buffers. */ 
printf("Enter Parameter number to be modified\n") ; 


/* for printf function */ 
/* for strlen function */ 
/* for atoi function */ 
/* for error code */ 
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gets(&bufValue[0]); 

printf("Enter new parameter value \n") ; 
gets (&buf Input [0]); 

/* Convert the input parmnum to a ULONG. */ 
ulParmNum = atoi(&bufValue[0]); 

switch (ulParmNum) 

{ 

case 10: 

/* Determine the size of the buffer. */ 
cbBuf = sizeof(PUSHORT) ; 

/* Convert the input parameter to a USHORT. */ 
usParm =(USH0RT)atoi (&buflnput[0] ) ; 

/* Point the buffer to the value. */ 
pBuf = &usParm; 
break; 
case 3: 
case 7: 
case 8: 

/* Determine the size of the buffer. */ 
cbBuf = strlen(&buflnput[0])+l; 

/* Point the buffer to the value. */ 
pBuf = (PSZ)&buf Input ; 
break; 
default: 

printf("Inval id number\n"); 

DosExit( EXIT_PR0CESS , 0 ) ; 
break; 

} 

/* Make the call. */ 

splerr = SplSetDevice(pszComputerName,pszPrintDeviceName,3L, 
pBuf, cbBuf, ulParmNum) ; 

/* Print out the result. */ 

printf ("SpISetDevice Err= %ld, Parameter 3 %d, cbBuf= %ld .ulParmNum 3 %ld\n" 
splerr, usParm, cbBuf, ulParmNum); 

DosExit( EXIT_PR0CESS , 0 ) ; 
return (splerr); 
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#define INCL_SPL /* Or use INCL_PM 7 


SPLERR SpISeUob (PSZ pszComputerName, PSZ pszQueueName, ULONG ulJob, 

ULONG ulLevel, PVOID pBuf, ULONG cbBuf, ULONG ulParmNum) 


This function modifies the instructions for a print job. 


Parameters 

pszComputerName (PSZ) - input 

Name of computer where job is to be modified. 

A NULL string specifies the local workstation. 

pszQueueName (PSZ) - input 
Queue Name. 

ulJob (ULONG) - input 

Job identification number. 

ulLevel (ULONG) - input 
Level of detail required. 

This must be 3. 

pBuf (PVOID) - input 
Buffer. 


cbBuf (ULONG) - input 
Size, in bytes, of Buffer. 

ulParmNum (ULONG) - input 
Parameter number. 


Specifies either that the entire PRJINF03 structure is to be modified, or that one specified 
parameter only is to be modified. 

If ulParmNum is 0, pBuf must contain a complete PR JINF03 structure. Otherwise, pBuf must 
contain a valid value corresponding to the parameter to be modified, as follows: 


Parameter 

pszNotifyName 

pszDataType 

pszParms 

uPosition 

pszComment 

pszDocument 

pszStatus 

uPriority 

pszQProcParms 

pDriverData 


Value 

PRJ_NOTIFYNAME_PARMNUM (3) 

PR J_DAT ATYPE_P AR MN U M (4) 
PRJ_PARMS_PARMNUM (5) 
PRJ_POSITION_PARMNUM (6) 
PRJ_COMMENT_PARMNUM (11) 
PRJ_DOCUMENT_PARMNUM (12) 

PR J_ST ATUSCOM ME NT_PARM N U M (13) 
PRJ_PRIORITY_PARMNUM (14) 
PRJ_PROCPARMS_PARMNUM (16) 
PRJ_DRIVERDATA_PARMNUM (18) 


uPosition must be given the appropriate value, as follows: 


Value Change 

0 No change 

1 Move to first place 

>1 Move to this position, or if the specified value is greater 

than the number of jobs in the queue, move to the end of 
the queue. 
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Returns 

NO_ERROR (0) 
ERRORACCESSDENIED (5) 
ERROR_NOT_SUPPORTED (50) 
ERROR_BAD_NETPATH (53) 

ERROR JNVALID PARAMETER (87) 
ERROR_INVALID_LEVEL (124) 
NERR_NetNotStarted (2102) 
NERR_BufTooSmall (2123) 
NERR_JobNotFound (2151) 
NERR_SpoolerNotLoaded (2161) 
NERR_JoblnvalldState (2164) 

NERR_SpooiNoMemory (2165) 
NERR_DrlverNotFound (2166) 
NERR_ProcNotFound (2168) 
NERRJnvalldComputer (2351) 


No errors occurred. 

Access is denied. 

This request is not supported by the network. 

The network path cannot be located. 

An invalid parameter is specified. 

The level parameter is invalid. 

The network program is not started. 

The API return buffer is too small. 

The print job does not exist. 

The spooler is not running. 

This operation cannot be performed on the print job in its 
current state. 

A spooler memory allocation failure occurred. 

The device driver does not exist. 

The queue processor is not installed. 

The computer name is invalid. 


Remarks 

The job priority is changed, if necessary, to the priority of the next job after the new position. If the 
spooler is restarted, the order in which jobs are put on the queue depends on the priority and age of 
the job. This order may be different from the order following the SpISetJob call. 

Users without administrator privilege can use SpISetJob only for jobs created when the same user 
name was logged on. They can move jobs backwards only, and cannot increase the job priority 
above the queue priority. 

A job created locally has no associated user name, and any user can set information locally for the 
job. Only an administrator can set information for a job on a remote server. 


Related Functions 

• SplEnumJob 

• SpIQueryJob 

• SpIQueryQueue 
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Example Code 

This sample code first gets a queue name and a jobid from the command prompt. It then prompts the 
user to enter a parameter number and a value for that number. 

Idefine INCL_BASE 
Idefine INCL_DOSMEMMGR 
Idefine INCL_SPL 
Idefine INCL_SPLDOSPRINT 
linclude <os2.h> 
linclude <stdio.h> 
linclude <stdlib.h> 
linclude <string.h> 
linclude <neterr.h> 

INT main (argc, argv) 

INT argc; 

CHAR *argv[] ; 

{ 

CHAR bufValue[2]={0}; 

CHAR buf Input [128] ={0} ; 

ULONG splerr ; 

ULONG cbBuf; 

ULONG ulParmNum ; 

ULONG ul Job ; 

USHORT usParm; 

PSZ pszComputerName ; 

PSZ pszQueueName ; 

PVOID pBuf; 

if (argc != 3) 

{ 

printf ("Syntax: sjset QueueName JobID \n“); 

DosExit( EXIT PROCESS , 0 ) ; 

} 

pszComputerName = (PSZ) NULL ; 

/* Set values to those entered at the prompt. */ 
pszQueueName = argv[l] ; 
ulJob = atoi (argv [2]); 

/* Request a parameter and the associated value. Store them in buffers. */ 
printf ("Enter Parameter number to be modified\n") ; 
gets(&bufValue[0]) ; 

printf("Enter new parameter value \n“); 
gets(&buflnput[0]) ; 

/* Convert the ParmNum to a ULONG. */ 
ulParmNum = atoi (&bufValue[0]); 
switch (ulParmNum) 

{ 

case 6: 
case 14: 

/* Calculate size of buffer needed if this is the parameter.*/ 
cbBuf = sizeof(PUSHORT) ; 

/* Convert input parameter into a USHORT. */ 
usParm =(USH0RT) atoi (&buf Input [0] ) ; 

/* Point pBuf to the value. */ 
pBuf = HusParm; 
break; 
case 3: 
case 4: 
case 5: 
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case 11: 
case 12: 
case 16: 

/* Calculate size of buffer needed if this is the parameter.*/ 
cbBuf = strlen(&buflnput[0])+l; 

/* Point pBuf to the value. */ 
pBuf = (PSZ)&buf Input; 
break; 
case 18: 

printf("In order to keep code simple, this is not implemented."); 
break; 
default: 

printf("Invalid number\n"); 

} 

splerr = SplSetJob(pszComputerName,pszQueueName,ul Job,3L, 
pBuf, cbBuf, ulParmNum) ; 

if ( ! splerr) 

printf ("Parameter was set."); 
else 

printf ("SpISetJob Error= %ld, Parameter 3 %d, Buf= %ld ,ParmNum= %ld\n" 
splerr, usParm, cbBuf, ulParmNum); 

DosExit( EXIT_PROCESS , 0 ) ; 
return (splerr) ; 
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#define INCL_SPL /* Or use INCL_PM */ 


SPLERR SpISetQueue (PSZ pszComputerName, PSZ pszQueueName, ULONG ulLevel, 
PVOID pBuf, ULONG cbBuf, ULONG IParmNum) 


This function modifies the configuration of a print queue. 


Parameters 

pszComputerName (PSZ) - input 

Name of computer where queue is to be modified. 

A NULL string specifies the local workstation. 

pszQueueName (PSZ) - input 
Queue name. 

ulLevel (ULONG) - input 
Level of detail required. 

This must be 3 or 6. 

pBuf (PVOID) - input 
Buffer. 


cbBuf (ULONG) - input 
Size, in bytes, of Buffer. 

IParmNum (ULONG) - input 
Parameter number. 


Specifies either that the entire PRQINF03 or PRQINF06 structure is to be modified, or that one 
specified parameter only is to be modified. 

If IParmNum is 0, pBuf must contain a complete PRQINF03 or PRQINF06 structure. Otherwise, 
pBuf must contain a valid value corresponding to the parameter to be modified, as follows: 


Parameter Value 


uPriority 

uStartTime 

uilntilTime 

pszSepFile 

pszPrProc 

pszParms 

pszComment 

fsType 

pszPrinters 

pszDriverName 

pDriverData 

pszRemoteComputerName 

pszRemoteQueueName 


PRQ_PRIORITY_PARMNUM (2) 
PRQ_STARTTIME_PARMNUM (3) 
PRQ_UNTILTIME_PARMNUM (4) 
PRQ_SEPARATOR_PARMNUM (5) 
PRQ_PROCESSOR_PARMNUM (6) 
PRQ_PARMS_PARMNUM (8) 
PRQ_COMMENT_PARMNUM (9) 
PRQ_TYPE_PARMNUM (10) 
PRQ_PRINTERS_PARMNUM (12) 
PRQ_DRIVERNAME_PARMNUM (13) 
PRQ_DRIVERDATA_PARMNUM (14) 
PRQ_REMOTE_COMPUTER_PARMNUM (15) 
PRQ_REMOTE_QUEUE_PARMNUM (16) 
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Returns 

NO_ERROR (0) 

ERROR ACCESS DENIED (5) 
ERROR_NOT_SUPPORTED (50) 
ERROR_BAD_NETPATH (53) 
ERRORJNVALID PARAMETER (87) 
ERROR_INVALID_LEVEL (124) 
NERR_NetNotStarted (2102) 
NERR_RedlrectedPath (2117) 
NERRBufTooSmall (2123) 
NERR_QNotFound (2150) 
NERR_DestNotFound (2152) 
NERR_DestNoRoom (2157) 

NERR_SpoolerNotLoaded (2161) 
NERR_DestlnvalldState (2162) 

NERR_SpoolNoMemory (2165) 
NERR_DriverNotFound (2166) 

N E R R_DataT y peln va lid (2167) 
NERR_ProcNotFound (2168) 
NERR_BadDev (2341) 
NERR_CommDevlnUse (2343) 
NERR_lnvalldComputer (2351) 


No errors occurred. 

Access is denied. 

This request is not supported by the network. 

The network path cannot be located. 

An invalid parameter is specified. 

The level parameter is invalid. 

The network program is not installed. 

The operation is invalid on a redirected resource. 

The API return buffer is too small. 

The printer queue does not exist. 

The printer destination cannot be found. 

The maximum number of printer destinations has been 
reached. 

The spooler is not running. 

This operation cannot be performed on the print 
destination. 

A spooler memory allocation failure occurred. 

The device driver does not exist. 

The datatype is not supported by the processor. 

The queue processor is not installed. 

The requested device is invalid. 

The requested device is invalid. 

The computer name is invalid. 


Remarks 

If the uPriority field in PRQINF03 or PRQINF06 is setto PRQ_NO_PRIORITY, the queue priority is not 
changed. 


Related Functions 

• SpICreateQueue 

• SplEnumDevice 

• SplEnumDriver 

• SplEnumQueue 

• SplEnumQueueProcessor 

• SpIQueryQueue 
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Example Code 

This sample code prompts the user to enter a parameter number and a value at the prompt. This 
value is then put into a buffer for use by the function. 

#define INCL_SPL 
#define INCL_SPLDOSPRINT 


#include <os2.h> 
linclude <stdio.h> 
linclude <stdlib.h> 
#include <string.h> 
linclude <neterr.h> 


/* for printf function */ 
/* for atoi function */ 
/* for strlen function */ 
/* for error codes */ 


INT main (argc, argv) 

I NT argc; 

CHAR *argv[] ; 

{ 

CHAR bufValue[2] = {0}; 
CHAR buf Input [128]= {0}; 
ULONG splerr ; 

ULONG cbBuf ; 

ULONG ulParmNum ; 

USHORT usParm ; 

PSZ pszComputerName ; 

PSZ pszQueueName ; 

PVOID pBuf; 


if (argc != 2) 

{ 

printf ("Syntax: setqryq QueueName \n"); 
DosExit( EXIT_PROCESS , 0 ) ; 


/* This function will be for the local workstation. 
pszComputerName = (PSZ) NULL ; 

/* Get the parameter from the command line. */ 

pszQueueName = argv[l]; 

/* Prompt the user for the parameter and values, and put them in buffers. */ 
printf("Enter Parameter number to be modified\n") ; 
gets(&bufValue[0]) ; 

printf("Enter new parameter value \n"); 
gets (&buf Input [0] ) ; 

/* Convert the ParmNum to a ULONG. */ 

ulParmNum = atoi (&bufValue[0]) ; 
switch (ul ParmNum) { 
case 2: 
case 3: 
case 4: 
case 10: 

/* Determine the size of the buffer needed. */ 

cbBuf = sizeof(PUSHORT) ; 

/* Convert the buffer input to a USHORT. */ 

usParm =(USH0RT)atoi (&buflnput[0]) ; 

/* Set the pBuf pointer to point to the value obtained. */ 

pBuf = SusParm; 
break; 
case 5: 
case 6: 
case 8: 
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case 9: 
case 12: 
case 13: 

/* Determine the size of the buffer needed. */ 

cbBuf = strlen(&buflnput[0])+l; 

/* Set the pBuf pointer to point to the value obtained from input. */ 
pBuf = (PSZ)&buf Input; 
break; 
case 14: 

printf("For simplicity this is not implemented."); 
break; 
default: 

printf("Invalid number\n"); 

DosExit( EXIT_PROCESS , 0 ) ; 
break; 

} 

/* Make the call with all the proper parameters. */ 

splerr = SplSetQueue(pszComputerName, pszQueueName, 3L, 
pBuf, cbBuf, ulParmNum) ; 

/* Print the resultant error code, and the parameters entered. */ 

printf(" SpISetQueue Error= %ld. Parameter 3 %d, cbBuf = %ld, 
ulParmNum= %ld\n", 

splerr, usParm, cbBuf, ulParmNum); 

DosExit( EXIT_PROCESS , 0 ) ; 
return (splerr); 
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Glossary 


A 

accelerator. A single key stroke that invokes an 
application-defined function. 

accelerator table. Used to define which key strokes are 
treated as accelerators and the commands they are 
translated into. 

access permission. All access rights that a user has 
regarding an object. 

action. One of a set of defined tasks that a computer 
performs. Users request the application to perform an 
action in several ways, such as typing a command, 
pressing a function key, or selecting the action name 
from an action bar or menu. 

action bar. The area at the top of a window that contains 
the choices currently available in the application 
program. 

action point. The current position on the screen at 
which the pointer is pointing. (Contrast with hot spot and 
input focus.) 

active program. A program currently running on the 
computer. See also interactive program, noninteractive 
program, and foreground program. 

active window. The window with which the user is 
currently interacting. 

address space. (1) The range of addresses available to 
a program. (2) The area of virtual storage available for a 
particular job. 

alphanumeric video output. Output to the logical video 
buffer when the video adapter is in text mode and the 
logical video buffer is addressed by an application as a 
rectangular array of character cells. 

anchor block. An area of Presentation Manager-internal 
resources allocated to a process or thread that calls 
Winlnitialize. 

anchor point. A point in a window used by a program 
designer or by a window manager to position a 
subsequently appearing window. 

ANSI. American National Standards Institute. 

APA. All points addressable. 

API. Application programming interface. The 
formally-defined programming language that is between 
an IBM application program and the user of the program. 
See also GPI. 

area. In computer graphics, a filled shape such as a 
solid rectangle. 

ASCII. American National Standard Code for 
Information Interchange. A coded character set 


consisting of 7-bit coded characters (8 bits including 
parity check), used for information interchange among 
data processing systems, data communications systems, 
and associated equipment. 

ASCIIZ. A string of ASCII characters that is terminated 
with a byte containing the value 0. 

aspect ratio. In computer graphics, the width-to-height 
ratio of an area, symbol, or shape. 

asynchronous. (1) Without regular time relationship. (2) 
Unexpected or unpredictable with respect to the 
execution of a program’s instructions. See also 
synchronous. 

atom. A constant that represents a string. Once a string 
has been defined as an atom, the atom can be used in 
place of the string to save space. Strings are associated 
with their respective atoms in an atom table. See also 
integer atom. 

atom table. Used to relate atoms with the strings that 
they represent. Also in the table is the mechanism by 
which the presence of a string can be checked. 

attributes. Characteristics or properties that can be 
controlled, usually to obtain a required appearance; for 
example, the color of a line. See also graphics attributes 
and segment attributes. 

AVIO. Advanced Video Input/Output. 

B 

background color. The color in which the background of 
a graphic primitive is drawn. 

background mix. An attribute that determines how the 
background of a graphic primitive is combined with the 
existing color of the graphics presentation space. 
Contrast with mix. 

background program. In multiprogramming, a program 
that executes with a low priority. Contrast with 
foreground program. 

Bezier curves. A mathematical technique of specifying 
smooth continuous lines and surfaces, which require a 
starting point and a finishing point with several 
intermediate points that influence or control the path of 
the linking curve. Named after Dr. P. Bezier. 

bit map. A representation in memory of the data 
displayed on an APA device, usually the screen. 

block. (1) A string of data elements recorded or 
transmitted as a unit. The elements may be characters, 
words, or logical records. (2) To combine two or more 
data elements in one block. 

border. A visual indication (for example, a separator 
line or a background color) of the boundaries of a 
window. 
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breakpoint. (1) An instruction in a program for halting 
execution. Breakpoints are usually established at 
positions in a program where halts, caused by external 
intervention, are convenient for restarting. (2) A place in 
a program, specified by a command or a condition, 
where the system halts execution and gives control to 
the workstation user or to a specified program. 

bucket. One or more fields in which the result of an 
operation is kept. 

buffer. (1) A portion of storage used to hold input or 
output data temporarily. (2) T o allocate and schedule the 
use of buffers. 

button. A mechanism on a pointing device, such as a 
mouse, used to request or initiate an action. Contrast 
with pushbutton and radio button. 

c 

cache. A high-speed buffer storage that contains 
frequently accessed instructions and data; it is used to 
reduce access time. 

cached micro presentation space. A presentation space 
from a Presentation Manager-owned store of micro 
presentation spaces. It can be used for drawing to a 
window only, and must be returned to the store when the 
task is complete. 

call. (1) The action of bringing a computer program, a 
routine, or a subroutine into effect, usually by specifying 
the entry conditions and jumping to an entry point. (2) T o 
transfer control to a procedure, program, routine, or 
subroutine. 

calling order. A sequence of instructions together with 
any associated data necessary to perform a call. Also 
known as calling sequence. 

cancel. An action that removes the current window or 
menu without processing it, and returns the previous 
window. 

CASE statement. In C, provides the body of a window 
procedure. There is one CASE statement for each 
message type written to take specific actions. 

cell. See character cell. 

CGA. Color graphics adapter. 

chained list. A list in which the data elements may be 
dispersed but in which each data element contains 
information for locating the next. Synonym for linked list. 

character. A letter, digit, or other symbol. 

character box. In computer graphics, the boundary that 
defines, in world coordinates, the horizontal and vertical 
space occupied by a single character from a character 
set. See also character mode. Contrast with character 
cell. 

character cell. The physical, rectangular space in which 
any single character is displayed on a screen or printer 
device. Position is addressed by row and column 
coordinates. Contrast with character box. 


character code. The means of addressing a character in 
a character set, sometimes called code point. 

character mode. The character mode, in conjunction 
with the font type, determines the extent to which 
graphics characters are affected by the character box, 
shear, and angle attributes. 

check box. A control window, shaped like a square 
button on the screen, that can be in a checked or 
unchecked state. It is used to select one or more items 
from a list. Contrast with radio button. 

check mark. The symbol that is used to indicate a 
selected item on a pull-down. 

child process. A process that is loaded and started by 
another process. Contrast with parent process. 

child window. A window that is positioned relative to 
another window (either a main window or another child 
window). Contrast with parent window. 

choice. An option that can be selected. The choice can 
be presented as text, as a symbol (number or letter), or 
as an icon (a pictorial symbol). 

class. See window class. 

class style. The set of properties that apply to every 
window in a window class. 

client area. The area in the center of a window that 
contains the main information of the window. 

clipboard. An area of main storage that can hold data 
being passed from one PM application to another. 
Various data formats can be stored. 

clipping. In computer graphics, removing those parts of 
a display image that lie outside a given boundary. 

clip limits. The area of the paper that can be reached by 
a printer or plotter. 

clipping path. A clipping boundary in world-coordinate 
space. 

CLOCKS. Character-device name reserved for the 
system clock. 

code page. An assignment of graphic characters and 
control-function meanings to all code points. 

code point. Synonym for character code. 

code segment. An executable section of programming 
code within a load module. 

color dithering. See dithering. 

command. The name and parameters associated with 
an action that a program can perform. 

command area. An area composed of a command field 
prompt and a command entry field. 

command entry field. An entry field in which users type 
commands. 
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command line. On a display screen, a display line 
usuallyatthe bottom of the screen, in which only 
commands can be entered. 

command prompt. A field prompt showing the location 
of the command entry field in a panel. 

Common Programming Interface (CPI). A consistent set 
of specifications for languages, commands, and calls to 
enable applications to be developed across all SAA 
environments. See also Systems Application 
Architecture. 

Common User Access (CUA). A set of rules that define 
the way information is presented on the screen, and the 
techniques for the user to interact with the information. 

compile. To translate a program written in a 
higher-level programming language into a machine 
language program. 

COM1, COM2, COM3. Character-device names reserved 
for serial ports 1 through 3. 

CON. Character-device name reserved for the console 
keyboard and screen. 

contiguous. Touching or joining at a common edge or 
boundary, for example, an unbroken consecutive series 
of storage locations. 

control. The means by which an operator gives input to 
an application. A choice corresponds to a control. 

Control Panel. In PM, a program used to set up user 
preferences that act globally across the system. 

Control Program. The basic function of OS/2, including 
DOS emulation and the support for keyboard, mouse, 
and video input/output. 

control window. A class of window used to handle a 
specific kind of user interaction. Radio buttons and 
check boxes are examples. 

correlation. The action of determining which element or 
object within a picture is at a given position on the 
display. This follows a pick operation. 

CPI. Common Programming Interface. 

critical extended attribute. An extended attribute that is 
necessary for the correct operation of the system or a 
particular application. 

CUA. Common User Access. 

current position. The point from which the next primitive 
will be drawn. 

cursor. A symbol displayed on the screen and 
associated with an input device. The cursor indicates 
where input from the device will be placed. Types of 
cursors include text cursors, graphics cursors, and 
selection cursors. Contrast with pointer and input focus. 


D 

data structure. (ISO) The syntactic structure of symbolic 
expressions and their storage-allocation characteristics. 

DBCS. See double-byte character set. 

deadlock. (1) Unresolved contention for the use of a 
resource. (2) An error condition in which processing 
cannot continue because each of two elements of the 
process is waiting for an action by, or a response from, 
the other. (3) An impasse that occurs when multiple 
processes are waiting for the availability of a resource 
that will not become available because it is being held by 
another process that is in a similar wait state. 

debug. To detect, diagnose, and eliminate errors in 
programs. 

declpolnt. In printing, one tenth of a point. There are 72 
points in an inch. 

default procedure. Function provided by the 
Presentation Interface that may be used to process 
standard messages from dialogs or windows. 

default value. A value used when no value is explicitly 
specified by the user. For example, in the graphics 
programming interface, the default line-type is ’solid'. 

descendant. A process or session that is loaded and 
started by a parent process or parent session. 

Desktop Manager. In PM, a window that displays a list 
of groups of programs, each of which can be started or 
stopped. 

desktop window. The window, corresponding to the 
physical device, against which all other types of windows 
are established. 

device context. A logical description of a data 
destination such as memory, metafile, display, printer, or 
plotter. See also direct device context, information 
device context, memory device context, metafile device 
context, queued device context, and screen device 
context. 

device driver. A file that contains the code needed to 
attach and use a device such as a display, printer, or 
plotter. 

device space. Coordinate space in which graphics are 
assembled after all GPI transformations have been 
applied. Device space is defined in device-specific units. 

dialog. The interchange of information between a 
computer and its user through a sequence of requests by 
the user and the presentation of responses by the 
computer. 

dialog box. A type of window that contains one or more 
controls for the formatted display and entry of data. Also 
known as a pop-up window. A modal dialog box is used 
to implement a pop-up window. 

Dialog Box Editor. A WYSIWYG editor that creates 
dialog boxes for communicating with the application 
user. 
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dialog item. A component (for example, a menu or a 
button) of a dialog box. Dialog items are also used when 
creating dialog templates. 

dialog tag language. A markup language used by the 
DTL compiler to create dialog objects. 

dialog template. The definition of a dialog box, which 
contains details of its position, appearance, and window 
ID, and the window ID of each of its child windows. 

direct device context. A logical description of a data 
destination that is a device other than the screen (for 
example, a printer or plotter), and where the output is 
not to go through the spooler. Its purpose is to satisfy 
queries. See also device context. 

direct manipulation. The action of using the mouse to 
move objects around the screen. For example, moving 
files and directories around in the File Manager. 

direct memory access (DMA). The transfer of data 
between main storage and input/output devices without 
intervention by the processor. 

directory. A type of file containing the names and 
controlling information for other files or other 
directories. 

display point. Synonym for pel. 

dithering. The process used in color displays whereby 
every other pel is set to one color, and the intermediate 
pels are set to another. Together they produce the effect 
of a third color at normal viewing distances. This 
process can only be used on solid areas of color; it does 
not work on narrow lines, for example. 

DMA. Direct memory access. 

double-byte character set (DBCS). A set of characters in 
which each character is represented by two bytes. 
Languages such as Japanese, Chinese, and Korean, 
which contain more characters than can be represented 
by 256 code points, require double-byte character sets. 
Since each character requires two bytes, the entering, 
displaying, and printing of DBCS characters requires 
hardware and software that can support DBCS. 

doubleword. A contiguous sequence of bits or 
characters that comprises two computer words and is 
capable of being addressed as a unit. 

dragging. In computer graphics, moving an object on 
the display screen as if it were attached to the pointer. 

drawing chain. See segment chain. 

drop. To fix the position of an object that is being 
dragged, by releasing the select button of the pointing 
device. 

DTL. See dialog tag language. 

dual-boot function. A feature of OS/2 that allows the 
user to start DOS from within OS/2, or OS/2 from within 
DOS. 

duplex. Pertaining to communication in which data can 
be sent and received at the same time. Synonymous 
with full duplex. 


dynamic linking. The process of resolving external 
references in a program module at load time or run time 
rather than during linking. 

dynamic-link library. A collection of executable 
programming code and data that is bound to an 
application at load time or run time, rather than during 
linking. The programming code and data in a dynamic 
link library can be shared by several applications 
simultaneously. 

dynamic-link module. A module that is linked at load 
time or run time. 

dynamic segments. Graphics segments drawn in 
exclusive-OR mix mode so that they can be moved from 
one screen position to another without affecting the rest 
of the displayed picture. 

dynamic storage. (1) A device that stores data in a 
manner that permits the data to move or vary with time 
such that the specified data is not always available for 
recovery. (2) A storage in which the cells require 
repetitive application of control signals in order to retain 
stored data. Such repetitive application of the control 
signals is called a refresh operation. A dynamic storage 
may use static addressing or sensing circuits. (3) See 
also static storage. 

E 

EBCDIC. Extended binary-coded decimal interchange 
code. A coded character set consisting of 8-bit coded 
characters (9 bits including parity check), used for 
information interchange among data processing 
systems, data communications systems, and associated 
equipment. 

EGA. Extended graphics adapter. 

8.3 file-name formal. A file-naming convention in which 
file names are limited to eight characters before and 
three characters after a single dot. Usually pronounced 
“eight-dot-three.” See also non-8.3 file-name format. 

element. An entry in a graphics segment that comprises 
one or more graphics orders and that is addressed by 
the element pointer. 

entry field. An area on the screen, usually highlighted in 
some manner, in which users type information. 

entry-field control. The means by which the application 
receives data entered by the user in an entry field. 

When it has the input focus, it displays a flashing pointer 
at the position where the next typed character will go. 

entry panel. A defined panel type containing one or 
more entry fields and protected information such as 
headings, prompts, and explanatory text. 

exception. An abnormal condition such as an I/O error 
encountered in processing a data set or a file. 

exclusive system semaphore. A system semaphore that 
can be modified only by threads within the same 
process. 
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exit. The action that terminates the current function and 
returns the user to a higher level function. Repeated exit 
requests return the user to the point from which all 
functions provided tothe system are accessible. 

Contrast with cancel. 

extended attribute. An additional piece of information 
about a file object, such as its data format or category. It 
consists of a name and a value. A file object may have 
more than one extended attribute associated with it. 

extended-choice selection. A mode that allows the user 
to select more than one item from a window. Not all 
windows allow extended choice selection. Contrast with 
multiple-choice selection. 

extended help. A facility that provides users with 
information about an entire application panel rather than 
a particular item on the panel. 

extent. Continuous space on a disk or diskette that is 
occupied by or reserved for a particular data set, data 
space, or file. 

F 

family-mode application. An application program that 
can run in the OS/2 environment and in the DOS 
environment. However, it cannot take advantage of 
many of the OS/2-mode facilities, such as multitasking, 
interprocess communication, and dynamic linking. 

FAT. File allocation table. 

FEA. Full extended attribute. 

field-level help. Information specific to the field on 
which the cursor is positioned. This help function is 
"contextual” because it provides information about a 
specific item as it is currently used; the information is 
dependent upon the context within the work session. 

file. A named set of records stored or processed as a 
unit. 

file allocation table (FAT). In IBM personal computers, a 
table used by the operating system to allocate space on 
a disk for a file, and to locate and chain together parts of 
the file that may be scattered on different sectors so that 
the file can be used in a random or sequential manner. 

file attribute. Any of the attributes that describe the 
characteristics of a file. 

File Manager. In PM, a program that displays 
directories and files, and allows various actions on them. 

file specification. The full identifier for a file, which 
includes its drive designation, path, file name, and 
extension. 

file system driver (FSD). A program that manages file 
I/O and controls the format of information on the storage 
media. 

fillet. A curve that is tangential to the end points of two 
adjoining lines. See also polyfillet. 

flag. (1) An indicator or parameter that shows the 
setting of a switch. (2) A character that signals the 
occurrence of some condition, such as the end of a word. 


focus. See input focus. 

font. A particular size and style of typeface that contains 
definitions of character sets, marker sets, and pattern 
sets. 

foreground program. The program with which the user 
is currently interacting. Also known as interactive 
program. Contrast with background program. 

frame. The part of a window that can contain several 
different visual elements specified by the application, but 
drawn and controlled by PM. The frame encloses the 
client area. 

frame styles. Different standard window layouts 
provided by PM. 

FSD. File system driver. 

full duplex. Synonym for duplex. 

full-screen application. An application program that 
occupies the whole screen. 

function. (1) In a programming language, a block, with 
or without formal parameters, whose execution is 
invoked by means of a call. (2) A set of related control 
statements that cause one or more programs to be 
performed. 

function key. A key that causes a specified sequence of 
operations to be performed when it is pressed, for 
example, FI and Alt-K. 

function key area. The area at the bottom of a window 
that contains function key assignments such as 
FI = Help. 

G 

GDT. Global Descriptor Table. 

general protection fault. An exception condition that 
occurs when a process attempts to use storage or a 
module that has some level of protection assigned to it, 
such as I/O privilege level. See also IOPL code segment. 

Global Descriptor Table (GDT). Defines code and data 
segments available to all tasks in an application. 

global dynamic-link module. A dynamic-link module that 
can be shared by all processes in the system that refer 
to the module name. 

global file-name character. A special character used to 
refer to a set of file objects with a common base name. 
The asterisk (*) and question mark (?) are used as global 
file-name characters. For example, *.EXE can be used to 
refer to a set of files with the extension EXE. 

glyph. A graphic symbol whose appearance conveys 
information. 

GPI. Graphics programming interface. The 
formally-defined programming language that is between 
an IBM graphics program and the user of the program. 
See also API. 
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graphics. A picture defined in terms of graphic 
primitives and graphics attributes. 

graphics attributes. Attributes that apply to graphic 
primitives. Examples are color, line type, and 
shading-pattern definition. See also segment attributes. 

graphics field. The clipping boundary that defines the 
visible part of the presentation-page contents. 

graphics model space. The conceptual coordinate 
space in which a picture is constructed after any model 
transforms have been applied. Also known as model 
space. 

graphic primitive. A single item of drawn graphics, such 
as a line, arc, or graphics text string. See also graphics 
segment. 

graphics segment. A sequence of related graphic 
primitives and graphics attributes. See also graphic 
primitive. 

graying. The indication that a choice on a pull-down is 
unavailable. 

group. A collection of logically-connected controls. For 
example, the buttons controlling paper size for a printer. 
See also program group. 

H 

handle. An identifier that represents an object, such as 
a device or window, to the Presentation Interface. 

hard error. An error condition on a network that 
requires either that the system be reconfigured, or that 
the source of the error be removed before the system 
can resume reliable operation. 

header. (1) System-defined control information that 
precedes user data. (2) The portion of a message that 
contains control information for the message, such as 
one or more destination fields, name of the originating 
station, input sequence number, character string 
indicating the type of message, and priority level for the 
message. 

help. A function that provides information about a 
specific field, an application panel, or information about 
the help facility. 

help index. A facility that allows the user to select topics 
for which help is available. 

help panel. A panel with information to assist users that 
is displayed in response to a help request from the user. 

help window. A Common User Access-defined 
secondary window that displays information when the 
user requests help. 

heap. An area of free storage available for dynamic 
allocation by an application. Its size varies according to 
the storage requirements of the application. 

hit testing. The means of identifying which window is 
associated with which input device event. 

hook. A mechanism by which procedures are called 
when certain events occur in the system. For example, 


the filtering of mouse and keyboard input before it is 
received by an application program. 

hook chain. A sequence of hook procedures that are 
“chained” together so that each event is passed, in turn, 
to each procedure in the chain. 

hot spot. The part of the pointer that must touch an 
object before it can be selected. This is usually the tip of 
the pointer. Contrast with action point. 

I 

icon. A pictorial representation of an item the user can 
select. Icons can represent items (such as a document 
file) that the user wants to work on, and actions that the 
user wants to perform. In PM, icons are used for data 
objects, system actions, and minimized programs. 

icon area. In PM, the area at the bottom of the screen 
that is normally used to display the icons for minimized 
programs. 

Icon Editor. The Presentation Manager-provided tool for 
creating icons. 

image font. A set of symbols, each of which is described 
in a rectangular array of pels. Some of the pels in the 
array are set to produce the image of the symbol. 
Contrast with outline font. 

information device context. A logical description of a 
data destination other than the screen (for example, a 
printer or plotter), but where no output will occur. Its 
purpose is to satisfy queries. See also device context. 

information panel. A defined panel type characterized 
by a body containing only protected information. 

input focus. The area of the screen that will receive 
input from an input device (typically the keyboard). 

input router. An internal OS/2 process that removes 
messages from the system queue. 

integer atom. A special kind of atom that represents a 
predefined system constant and carries no storage 
overhead. For example, names of window classes 
provided by PM are expressed as integer atoms. 

interactive graphics. Graphics that can be moved or 
manipulated by a user at a terminal. 

interactive program. A program that is running (active) 
and is ready to receive (or is receiving) input from the 
user. Compare with active program and contrast with 
noninteractive program. 

Also known as a foreground program. 

interchange file. Data that can be sent from one 
Presentation Interface application to another. 

interval timer. (1) A timer that provides program 
interruptions on a program-controlled basis. (2) An 
electronic counter that counts intervals of time under 
program control. 

lOCtl. A device-specific command that requests a 
function of a device driver through the DosDevlOCtl 
function. 
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I/O operation. An input operation to, or output operation 
from a device attached to a computer. 

IOPL. Input/output privilege level. 

IOPL code segment. An IOPL executable section of 
programming code that enables an application to directly 
manipulate hardware interrupts and ports without 
replacing the device driver. See also privilege level. 

J 

journal. A special-purpose file that is used to record 
changes made in the system. 

K 

Kanji. A graphic character set used in Japanese 
ideographic alphabets. 

KBD$. Character-device name reserved for the 
keyboard. 

kernel. The part of an operating system that performs 
basic functions, such as allocating hardware resources. 

kerning. The design of graphics characters so that their 
character boxes overlap. Used to space text 
proportionally. 

keys help. A facility that gives users a listing of ail the 
key assignments for the current application. 

L 

label. In a graphics segment, an identifier of one or 
more elements that is used when editing the segment. 

language support procedure. Function provided by the 
Presentation Interface for applications that do not, or 
cannot (as in the case of COBOL and FORTRAN 
programs), provide their own dialog or window 
procedures. 

LDT. Local Descriptor Table. 

LIFO stack. A data stack from which data is retrieved in 
last-in, first-out order. 

linked list. Synonym for chained list. 

list box. A control window containing a vertical list of 
selectable descriptions. 

list panel. A defined panel type that displays a list of 
items from which users can select one or more choices 
and then specify one or more actions to work on those 
choices. 

load-on-call. A function of a linkage editor that allows 
selected segments of the module to be disk resident 
while other segments are executing. Disk resident 
segments are loaded for execution and given control 
when any entry point that they contain is called. 

load time. The point in time at which a program module 
is loaded into main storage for execution. 


local area network (LAN). A data network located on the 
user’s premises in which serial transmission is used for 
direct data communication among data stations. 

Local Descriptor Table (LDT). Defines code and data 
segments specific to a single task. 

lock. A serialization mechanism by means of which a 
resource is restricted for use by the holder of the lock. 

LPT1, LPT2, LPT3. Character-device names reserved for 
parallel printers 1 through 3. 

M 

main window. The window that is positioned relative to 
the desktop window. 

map. (1) A set of values having a defined 
correspondence with the quantities or values of another 
set. (2) To establish a set of values having a defined 
correspondence with the quantities or values of another 
set. 

marker box. In computer graphics, the boundary that 
defines, in world coordinates, the horizontal and vertical 
space occupied by a single marker from a marker set. 

marker symbol. A symbol centered on a point. Graphs 
and charts can use marker symbols to indicate the 
plotted points. 

maximize. A window-sizing action that makes the 
window the largest size possible. 

media window. The part of the physical device (display, 
printer, or plotter) on which a picture is presented. 

memory device context. A logical description of a data 
destination that is a memory bit map. See also device 
context. 

memory management. A feature of the operating 
system for allocating, sharing, and freeing main storage. 

menu. A type of panel that consists of one or more 
selection fields. Also called a menu panel. 

message. (1) In PM, a packet of data used for 
communication between the Presentation Interface and 
windowed applications. (2) In a user interface, 
information not requested by users but presented to 
users by the computer in response to a user action or 
internal process. 

message filter. The means of selecting which messages 
from a specific window will be handled by the 
application. 

message queue. A sequenced collection of messages to 
be read by the application. 

metafile. The generic name for the definition of the 
contents of a picture. Metafiles are used to allow 
pictures to be used by other applications. 

metafile device context. A logical description of a data 
destination that is a metafile, which is used for graphics 
interchange. See also device context. 
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metalanguage. A language used to specify another 
language. For example, data types can be described 
using a metalanguage so as to make the descriptions 
independent of any one computer language. 

mickey. A unit of measurement for physical mouse 
motion whose value depends on the mouse device driver 
currently loaded. 

micro presentation space. A graphics presentation 
space in which a restricted set of the GPI function calls is 
available. 

minimize. A window-sizing action that makes the 
window the smallest size possible. In PM, minimized 
windows are represented by icons. 

mix. An attribute that determines how the foreground of 
a graphic primitive is combined with the existing color of 
graphics output. Also known as foreground mix. 

Contrast with background mix. 

mixed character string. A string containing a mixture of 
one-byte and Kanji or Hangeul (two-byte) characters. 

mnemonic. A method of selecting an item on a 
pull-down by means of typing the highlighted letter in the 
menu item. 

modal dialog box. The type of control that allows the 
operator to perform input operations on only the current 
dialog box or one of its child windows. Also known as a 
serial dialog box. Contrast with parallel dialog box. 

modeless dialog box. The type of control that allows the 
operator to perform input operations on any of the 
application's windows. Also known as a parallel dialog 
box. Contrast with modal dialog box. 

model space. See graphics model space. 

module definition file. A fi le that describes the code 
segments within a load module. For example, it 
indicates whether a code segment is loadable before 
module execution begins (preload), or loadable only 
when referred to at run time (load-on-call). 

mouse. A hand-held device that is moved around to 
position the pointer on the screen. 

MOUSES. Character-device name reserved for a mouse. 

multiple-choice selection. A mode that allows users to 
select any number of choices, including none at all. See 
also check box. Contrast with extended-choice 
selection. 

multitasking. The concurrent processing of applications 
or parts of applications. A running application and its 
data are protected from other concurrently running 
applications. 

N 

named pipe. A named buffer that provides 
client-to-server, server-to-client, or full duplex 
communication between unrelated processes. Contrast 
with unnamed pipe. 

noncritical extended attribute. An extended attribute 
that is not necessary for the function of an application. 


nondestructive read. A read process that does not 
erase the data in the source location. 

non-8.3 tile-name format. A file-naming convention in 
which path names can consist of up to 255 characters. 
See also 8.3 file-name format. 

nonlnteractlve program. A program that is running 
(active) but is not ready to receive input from the user. 
Compare with active program, and contrast with 
interactive program. 

nonretalned graphics. Graphic primitives that are not 
remembered by the Presentation Interface once they 
have been drawn. Contrast with retained graphics. 

NUL. Character-device name reserved for a nonexistent 
(dummy) device. 

null-terminated string. A string of (n + 1) characters 
where the (n + 1)th character is the 'null' character 
(XW), and is used to represent an n-character string 
with implicit length. Also known as 'zero-terminated' 
string and 'ASCIIZ' string. 

o 

object window. A window that does not have a parent, 
but which may have child windows. An object window 
cannot be presented on a device. 

open. To start working with a file, directory, or other 
object. 

outline font. A set of symbols, each of which is created 
as a series of lines and curves. Synonymous with vector 
font. Contrast with image font. 

output area. The area of the output device within which 
the picture is to be displayed, printed, or plotted. 

owner window. A window into which specific events that 
occur in another (owned) window are reported. 

owning process. The process that owns the resources 
that may be shared with other processes. 

P 

page. A 4KB segment of contiguous physical memory. 

page viewport. A boundary in device coordinates that 
defines the area of the output device in which graphics 
are to be displayed. The presentation-page contents are 
transformed automatically to the page viewport in device 
space. 

paint. The action of drawing or redrawing the contents 
of a window. 

panel. A particular arrangement of information grouped 
together for presentation to the user in a window. 

panel area. An area within a panel that contains related 
information. The three major Common User 
Access-defined panel areas are the action bar, the 
function key area, and the panel body. 
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panel body. The portion of a panel not occupied by the 
action bar, function key area, title or scroll bars. The 
panel body may contain protected information, selection 
fields, and entry fields. The layout and content of the 
panel body determine the panel type. 

panel body area. The part of a window not occupied by 
the action bar or function key area. The panel body area 
may contain information, selection fields, and entry 
fields. Also known as client area. 

panel body area separator. A line or color boundary 
that provides users with a visual distinction between two 
adjacent areas of a panel. 

panel definition. A description of the contents and 
characteristics of a panel. A panel definition is the 
application developer’s mechanism for predefining the 
format to be presented to users in a window. 

panel ID. A panel element located in the upper left-hand 
corner of a panel body that identifies that particular 
panel within the application. 

panel title. A panel element that identifies the 
information in the panel. 

paper size. The size of paper, defined in either standard 
U.S. or European names (for example, A, B, A4), and 
measured in inches or millimeters respectively. 

parallel dialog box. See modeless dialog box. 

parent process. A process that loads and starts other 
processes. Contrast with child process. 

parent window. The window relative to which one or 
more child windows are positioned. Contrast with child 
window. 

partition. (1) A fixed-size division of storage. (2) On an 
IBM personal computer fixed disk, one of four possible 
storage areas of variable size; one may be accessed by 
DOS, and each of the others may be assigned to another 
operating system. 

path. The part of a file specification that lists a series of 
directory names. Each directory name is separated by 
the backslash character. In the file specification 
C:\MYFILES\MISC\GLOSSARY.SCR, the path consists of 
MYFILESVMISCV 

pel. The smallest area of a display screen capable of 
being addressed and switched between visible and 
invisible states. Synonym for display point, pixel, and 
picture element. 

pick. To select part of a displayed object using the 
pointer. 

picture chain. See segment chain. 
picture element. Synonym for pel. 

PID. Process identification. 

pipe. A named or unnamed buffer used to pass data 
between processes. A process reads from or writes to a 
pipe as if the pipe were a standard-input or 


standard-output file. See also named pipe and unnamed 
Pipe- 

pixel. Synonym for pel. 

plotter. An output device that uses pens to draw its 
output on paper or on transparency foils. 

PM. Presentation Manager. 

pointer. (1) The symbol displayed on the screen that is 
moved by a pointing device, such as a mouse. The 
pointer is used to point at items that users can select. 
Contrast with cursor. (2) A data element that indicates 
the location of another data element. 

POINTERS. Character-device name reserved for a 
pointer device (mouse screen support). 

pointing device. A device (such as a mouse) used to 
move a pointer on the screen. 

pointings. Pairs of x-y coordinates produced by an 
operator defining positions on a screen with a pointing 
device, such as a mouse. 

polyfillet. A curve based on a sequence of lines. It is 
tangential to the end points of the first and last lines, and 
tangential also to the midpoints of all other lines. See 
also fillet. 

polyline. A sequence of adjoining lines. 

pop. To retrieve an item from a last-in-first-out stack of 
items. Contrast with push. 

pop-up window. A window that appears on top of 
another window in a dialog. Each pop-up window must 
be completed before returning to the underlying window. 

Presentation Manager (PM). The visual component of 
OS/2 that presents, in windows, a graphics-based 
interface to applications and files installed and running 
in OS/2. 

presentation page. The coordinate space in which a 
picture is assembled for display. 

presentation space (PS). Contains the 
device-independent definition of a picture. 

primary window. The window in which the main dialog 
between the user and the application takes place. In a 
multiprogramming environment, each application starts 
in its own primary window. The primary window remains 
for the duration of the application, although the panel 
displayed will change as the user’s dialog moves 
forward. See also secondary window. 

primitive. See graphic primitive. 

primitive attribute. A specifiable characteristic of a 
graphic primitive. See graphics attributes. 

print job. The result of sending a document or picture to 
be printed. 

Print Manager. In PM, the part of the spooler that 
manages the spooling process. It also allows users to 
view print queues and to manipulate print jobs. 
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privilege level. A protection level imposed by the 
hardware architecture of the IBM personal computer. 
There are four privilege levels (number 0 through 3). 
Only certain types of programs are allowed to execute at 
each privilege level. See also IOPL code segment. 

procedure call. In programming languages, a language 
construct for invoking execution of a procedure. 

process. An instance of an executing application and 
the resources it is using. 

program details. Information about a program that is 
specified in the Program Manager window and is used 
when the program is started. 

program group. In PM, several programs that can be 
acted upon as a single entity. 

program name. The full file specification of a program. 
Contrast with program title. 

program title. The name of a program as it is listed in 
the Program Manager window. Contrast with program 
name. 

prompt. A displayed symbol or message that requests 
input from the user or gives operational information. 

The user must respond to the prompt in order to 
proceed. 

protocol. A set of semantic and syntactic rules that 
determines the behavior o functional units in achieving 
communication. 

pseudocode. An artificial language used to describe 
computer program algorithms without using the syntax of 
any particular programming language. 

pull-down. An action bar extension that displays a list of 
choices available for a selected action bar choice. After 
users select an action bar choice, the pull-down appears 
with the list of choices. Additional pop-up windows may 
appear from pull-down choices to further extend the 
actions available to users. 

push. To add an item to a last-in-first-out stack of items. 
Contrast with pop. 

pushbutton. A control window, shaped like a 
round-cornered rectangle and containing text, that 
invokes an immediate action, such as ’enter’ or 'cancel'. 

Q 

queue. A linked list of elements waiting to be 
processed. For example, a queue may be a list of print 
jobs waiting to be printed. 

queued device context. A logical description of a data 
destination (for example, a printer or plotter) where the 
output is to go through the spooler. See also device 
context. 


R 

radio button. A control window, shaped like a round 
button on the screen, that can be in a checked or 
unchecked state. It is used to select a single item from 
list. Contrast with check box. 

HAS. Reliability, availability, and serviceability. 

raster. (1) In computer graphics, a predetermined 
pattern of lines that provides uniform coverage of a 
display space. (2) The coordinate grid that divides the 
display area of a display device. 

read-only file. A file that may be read from but not 
written to. 

realize. To cause the system to ensure, wherever 
possible, that the physical color table of a device is set to 
the closest possible match in the logical color table. 

recursive routine. A routine that can call itself or be 
called by another routine called by the recursive routine. 

reentrant. The attribute of a program or routine that 
allows the same copy of the program or routine to be 
used concurrently by two or more tasks. 

reference phrase. A word or phrase that is emphasized 
in a device-dependent manner to inform the user that 
additional information for the word or phrase is 
available. 

reference phrase help. Provides help information for a 
selectable word or phrase. 

refresh. To update a window, with changed information, 
to its current status. 

region. A clipping boundary in device space. 

register. A storage device having a specified storage 
capacity such as a bit, byte, or computer word, and 
usually intended for a special purpose. 

remote file system. A file-system driver that gains 
access to a remote system without a block device driver. 

resource. The means of providing extra information 
used in the definition of a window. A resource can 
contain definitions of fonts, templates, accelerators, and 
mnemonics; the definitions are held in a resource file. 

resource file. A file containing information used in the 
definition of a window. Definitions can be of fonts, 
templates, accelerators, and mnemonics. 

restore. To return a window to its original size or 
position following a sizing or moving action. 

retained graphics. Graphic primitives that are 
remembered by the Presentation Interface after they 
have been drawn. Contrast with nonretained graphics. 

return code. (1) A code used to influence the execution 
of succeeding instructions. (2) A value returned to a 
program to indicate the results of an operation 
requested by that program. 

reverse video. A form of alphanumeric highlighting for a 
character, field, or cursor, in which its color is 
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exchanged with that of its background. For example, 
changing a red character on a black background to a 
black character on a red background. 

RGB. Red-green-blue. For example, “RGB display”. 

roman. Relating to a type style with upright characters. 

root segment. In a hierarchical database, the highest 
segment in the tree structure. 

run time. (1) Any instant at which a program is being 
executed. (2) The time during which an instruction in an 
instruction register is decoded and performed. 

s 

SAA. Systems Application Architecture. 

scheduler. A computer program designed to perform 
functions such as scheduling, initiation, and termination 
of jobs. 

screen. The physical surface of a work station or 
terminal upon which information is presented to users. 

screen device context. A logical description of a data 
destination that is a particular window on the screen. 

See also device context. 

SCREENS. Character-device name reserved for the 
display screen. 

scroll bar. A control window, horizontally or vertically 
aligned, that allows the userto scroll additional data into 
an associated panel area. 

scrollable entry field. An entry field larger than the 
visible field. 

scrollable selection field. A selection field that contains 
more choices than are visible. 

scrolling. Moving a display image vertically or 
horizontally in a manner such that new data appears at 
one edge, as existing data disappears at the opposite 
edge. 

secondary window. A type of window associated with 
the primary window in a dialog. A secondary window 
begins a secondary and parallel dialog that runs at the 
same time as the primary dialog. 

sector. An addressable subdivision of a track used to 
record one block of program code or data on a disk or 
diskette. 

segment. See graphics segment. 

segment attributes. Attributes that apply to the segment 
as an entity, as opposed to the individual primitives 
within the segment. For example, the visibility or 
detectability of a segment. 

segment chain. All segments in a graphics presentation 
space that are defined with the ’chained’ attribute. 
Synonym for picture chain. 

segment priority. The order in which segments are 
drawn. 


segment store. An area in a normal graphics 
presentation space where retained graphics segments 
are stored. 

select. To mark or choose an item. Note that select 
means to mark or type in a choice on the screen; enter 
means to send all selected choices to the computer for 
processing. 

select button. The button on a pointing device, such as 
a mouse, that is pressed to select a menu choice. Also 
known as button 1. 

selection cursor. A type of cursor used to indicate the 
choice or entry field users want to interact with. It is 
represented by highlighting the item that it is currently 
positioned on. 

selection field. A field containing a list of choices from 
which the user can select one or more. 

semaphore. An object used by multi-threaded 
applications for signalling purposes and for controlling 
access to serially reusable resources. 

separator. See panel body area separator. 

serial dialog box. See modal dialog box. 

serialization. The consecutive ordering of items. 

serialize. To ensure that one or more events occur in a 
specified sequence. 

serially reusable resource (SRR). A logical resource or 
object that can be accessed by only one task at a time. 

session. A routing mechanism for user interaction via 
the console; a complete environment that determines 
how an application runs and how users interact with the 
application. OS/2 can manage more than one session at 
a time, and more than one process can run in a session. 
Each session has its own set of environment variables 
that determine where OS/2 looks for dynamic-link 
libraries and other important files. 

shadow box. The area on the screen that follows mouse 
movements and shows what shape the window will take 
if the mouse button is released. 

shared data. Data that is used by two or more 
programs. 

shared memory. Memory that is used by two or more 
programs. 

shear. The tilt of graphics text when each character 
leans to the left or right while retaining a horizontal 
baseline. 

shell. (1) A software interface between a user and the 
operating system of a computer. Shell programs 
interpret commands and user interactions on devices 
such as keyboards, pointing devices, and touch-sensitive 
screens, and communicate them to the operating system. 
(2) Software that allows a kernel program to run under 
different operating-system environments. 

Shutdown. The procedure required before the computer 
is switched off to ensure that data is not lost. 
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sibling processes. Child processes that have the same 
parent process. 

sibling windows. Child windows that have the same 
parent window. 

slider box. An area on the scroll bar that indicates the 
size and position of the visible information in a panel 
area in relation to the information available. Also known 
as thumb mark. 

source file. A file that contains source statements for 
items such as high-level language programs and data 
description specifications. 

source statement. A statement written in a 
programming language. 

specific dynamic-link module. A dynamic-link module 
created for the exclusive use of an application. 

spline. A sequence of one or more B&zier curves. 

spooler. A program that intercepts the data going to 
printer devices and writes it to disk. The data is printed 
or plotted when it is complete, and the required device is 
available. The spooler prevents output from different 
sources from being intermixed. 

stack. A list constructed and maintained so that the next 
data element to be retrieved is the most recently stored. 
This method is characterized as last-in-first-out (LIFO). 

standard window. A collection of window elements that 
form a panel. The standard window can include one or 
more of the following window elements: sizing borders, 
system menu icon, title bar, maximize/minimize/restore 
icons, action bar and pull-downs, scroll bars, and client 
area. 

static control. The means by which the application 
presents descriptive information (for example, headings 
and descriptors) to the user. The user cannot change 
this information. 

static storage. (1) A read/write storage unit in which 
data is retained in the absence of control signals. Static 
storage may use dynamic addressing or sensing circuits. 
(2) Storage other than dynamic storage. 

style. See window style. 

suballocation. The allocation of a part of one extent for 
occupancy by elements of a component other than the 
one occupying the remainder of the extent. 

subdirectory. In an IBM personal computer, a file 
referred to in a root directory that contains the names of 
other files stored on the diskette or fixed disk. 

swapping. (1) A process that interchanges the contents 
of an area of real storage with the contents of an area in 
auxiliary storage. (2) In a system with virtual storage, a 
paging technique that writes the active pages of a job to 
auxiliary storage and reads pages of another job from 
auxiliary storage into real storage. (3) The process of 
temporarily removing an active job from main storage, 
saving it on disk, and processing another job in the area 
of main storage formerly occupied by the first job. 

switch. (1) An action that moves the input focus from 
one area to another. This can be within the same 


window or from one window to another. (2) In a 
computer program, a conditional instruction and an 
indicator to be interrogated by that instruction. (3) A 
device or programming technique for making a selection, 
for example, a toggle, a conditional jump. 

switch list. See Task List. 

symbolic identifier. A text string that equates to an 
integer value in an include file, that is used to identify a 
programming object. 

synchronous. Pertaining to events or operations that 
are predictable or occur at the same time. See also 
asynchronous. 

System Menu. In PM, the pull-down in the top left corner 
of a window that allows it to be moved and sized with the 
keyboard. 

system queue. This is the master queue for all pointer 
device or keyboard events. 

Systems Application Architecture (SAA). A formal set of 
rules that enables applications to be run without 
modification in different computer environments. 

T 

tag. One or more characters attached to a set of data 
that defines the formatting or other characteristics of the 
set, including its definition. 

Task List. In PM, the list of programs that are active. 

The list can be used to switch to a program and to stop 
programs. 

template. An ASCII-text definition of an action bar and 
pull-down menu, held in a resource file, or as a data 
structure in program memory. 

text. Characters or symbols. 

text cursor. A symbol displayed in an entry field that 
indicates where typed input will appear. 

text window. Also known as the VIO window. 

text-windowed application. The environment in which 
the operating system performs advanced&hyphn. video 
input and output operations. 

thread. A unit of execution within a process. It uses the 
resources of the process. 

thumb mark. The portion of the scroll bar that describes 
the range and properties of the data that is currently 
visible in a window. Also known as a slider box. 

tilde. A mark used to denote the character that is to be 
used as a mnemonic when selecting text items within a 
menu. 

time slice. (1) An interval of time on the processing unit 
allocated for use in performing a task. After the interval 
has expired, processing-unit time is allocated to another 
task, so a task cannot monopolize processing-unit time 
beyond a fixed limit. (2) In systems with time sharing, a 
segment of time allocated to a terminal job. 
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title bar. The area at the top of a window that contains 
the windowtitle. Thetitlebar is highlighted when that 
window has the input focus. Contrast with panel title. 

transaction. An exchange between a workstation and 
another device that accomplishes a particular action or 
result. 

transform. (1) The action of modifying a picture by 
scaling, shearing, reflecting, rotating, or translating. (2) 
The object that performs or defines such a modification; 
also referred to as a transformation. 

Tree. In PM, the window in the File Manager that shows 
the organization of drives and directories. 

truncate. (1) To end a computational process in 
accordance with some rule. (2) To remove the beginning 
or ending elements of a string. (3) T o drop data that 
cannot be printed or displayed in the line width specified 
or available. (4) To shorten a field or statement to a 
specified length. 

u 

unnamed pipe. A circular buffer, created in memory, 
used by related processes to communicate with one 
another. Contrast with named pipe. 

update region. A system-provided area of dynamic 
storage containing one or more (not necessarily 
contiguous) rectangular areas of a window, that are 
visually invalid or incorrect, and therefore in need of 
repainting. 

user Interface. Hardware, software, or both that allows 
a user to interact with and perform operations on a 
system, program, or device. 

User Shell. A component of OS/2 that uses a 
graphics-based, windowed interface to allow the user to 
manage applications and files installed and running 
under OS/2. 

utility program. (1) A computer program in general 
support of computer processes; for example, a 
diagnostic program, a trace program, a sort program. 

(2) A program designed to perform an everyday task 
such as copying data from one storage device to 
another. 

V 

vector font. A set of symbols, each of which is created 
as a series of lines and curves. Synonymous with 
outline font. Contrast with image font. 

VGA. Video g raphics array. 

viewing pipeline. The series of transformations applied 
to a graphic object to map the object to the device on 
which it is to be presented. 

viewing window. Clipping boundary that defines the 
visible part of model space. 

VIO. Video Input/Output. 


virtual memory (VM). Addressable space that is 
apparent to the user as the processor storage space, but 
not having a fixed physical location. 

virtual storage. Synonymous with virtual memory. 

visible region. A window’s presentation space, clipped 
to the boundary of the window and the boundaries of any 
overlying window. 

volume. (1) A file-system driver that uses a block device 
driver for input and output operations to a local or 
remote device. (2) A portion of data, together with its 
data carrier, that can be handled conveniently as a unit. 

w 

wild-card character. The global file-name characters 
asterisk (*) and question mark (?). 

window. A rectangular area of the screen with visible 
boundaries within which information is displayed. A 
window can be smaller than or the same size as the 
screen. Windows can appear to overlap on the screen. 

window class. The grouping of windows whose 
processing needs conform to the services provided by 
one window procedure. 

window coordinates. The means by which a window 
position or size is defined; measured in device units, or 
pels. 

window procedure. Code that is activated in response 
to a message. The procedure controls the appearance 
and behavior of its associated windows. 

window rectangle. The means by which the size and 
position of a window is described in relation to the 
desktop window. 

window style. The set of properties that influence how 
events related to a particular window will be processed. 

workstation. A display screen together with attachments 
such as a keyboard, a local copy device, or a tablet. 

world coordinates. Application-convenient coordinates 
used for drawing graphics. 

world-coordinate space. Coordinate space in which 
graphics are defined before transformations are applied. 

WYSIWYG. What You See Is What You Get. A capability 
that enables text to be displayed on a screen in the same 
way it will be formatted on a printer. 

z 

z-order. The order in which sibling windows are 
presented. The topmost sibling window obscures any 
portion of the siblings that it overlaps; the same effect 
occurs down through the order of lower sibling windows. 

zooming. In graphics applications, the process of 
increasing or decreasing the size of picture. 
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Index 


A 

ABB_* values 5-405, 5-463 
ACCEL A-1 
accelerator table 
copy 8-37 
create 8-44 
destroy 8-98 
load 8-234 
query 8-291 
set 8-439 
translate 8-550 
ACCELTABLE A-1 
ACCELTABLE statement 32-9 
Access a DRAGINFO Structure 3-26 
Access Drag Information 3-4 
Add Atom 8-7 
Add Switch Entry 8-9 
Add Text to DDF Buffer 4-39 
additional metrics F-9 
addressing elements in arrays 1-5 
alarm sound 8-11 
Allocate DRAGINFO Structure 3-7 
Allocate DRAGTRANSFER Structures 3-9 
AM_* values 5-228, 5-401 
Animate Palette 5-8 
application-supplied functions 10-1 
Applications 

Windowed PM 34-1 
Arabic text 5-435 
arc 

create 5-199 
full 5-148, 5-189 
partial 5-188 
query parameters 5-226 
set current parameters 5-398 
set default parameters 5-460 
Arc at a Given Position 33-3 
Arc at Current Position 33-3 
ARCPARAMS A-2 
AREABUNDLE A-2 
areas 

begin construction 5-13 
construction of interior 5-15 
end construction 5-128 
arrays 

addressing elements in 1-5 
convert 5-53, 5-55 
ASCII 8-321,8-459,34-23 
ASCII MIXED code pages 34-23 
Associate 5-11 
Associate Help Instance 8-13 
ASSOCT ABLE statement 32-10 
ATOM A-2 

attribute primitive type 5-404 
attribute primitive types 5-462 
attribute values 

character 5-404, 5-462 
image 5-405, 5-463 
line 5-404, 5-462 
marker 5-405, 5-463 
pattern (area) 5-405, 5-463 


attributes 

character-set 5-443 
color 5-453 

cosmetic line width 5-498 
foreground color mix 5-511 
geometric line width 5-500 
line type 5-495 
line width 5-498 
marker box 5-504 
marker set 5-506 
marker symbol 5-503 
pattern 5-522 
pattern set 5-526 
query mode 5-228 
restore saved 5-217 
segment 5-539 
set 5-404 
set default 5-462 
set line-end 5-491 
set line-join 5-493 
specify mode 5-401 

ATTR_* values 5-304, 5-351 , 5-488, 5-538 

B 

background 

query color 5-231, 5-232 
query color-mixing mode 5-232 
query mix 5-232 
BANDRECT A-2 
BA_* values 5-13 
BBO_* values 5-24, 5-1 13, 5-568 
BDS_* values 13-3 
Begin Area 5-13, 33-3 
Begin Definition List 4-2 
Begin Dragging Files 3-16 
Begin Element 5-17, 33-4 
Begin Image at Current Position 33-5 
Begin Image at Given Position 33-5 
Begin Paint 8-18 
Begin Path 5-19, 33-5 
Begin Window Enumeration 8-16 
Bezier Curve at Current Poition 33-6 
Bezier Curve at Given Position 33-6 
Bezier splines, create 5-215 
Bit Bit 5-23 
bit maps 

color 5-25,5-114,5-569 

copy rectangle of image data 5-23, 5-567 

create 5-71 

data D-1 

delete 5-90 

draw 8-118 

example D-1 

file format D-2 

get system 8-194 

information tables D-1 

load 5-161 

monochrome 5-25,5-114,5-569 
query bits 5-233 
query device formats 5-280 
query dimension 5-236 
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bit maps (continued) 
query handle 5-239 
query info-header 5-237 
query number of local identifiers 5-329 
query parameters 5-240 
query set identifiers 5-359 
set as currently selected 5-418 
set bits 5-420 
set identifier 5-425 
standard formats D-1 

transfer data from application storage 5-420 
bit-map tag 
delete 5-106 
Bitblt 33-7 
BITMAPINFO A-3 
BITMAPINFOHEADER A-6 
BITMAPINFOHEADER2 A-6 
BITMAPINF02 A-3 
bits 

draw 5-112 

BKM_CALCPAGERECT 25-4 
BKM_DELETEPAGE 25-5 
BKMJNSERTPAGE 25-6 
BKMJNVALIDATETABS 25-7 
BKM_QUERYPAGECOUNT 25-7 
BKM_QUERYPAGEDATA 25-8 
BKM_QUERYPAGEID 25-9 
BKM_QUERYPAGESTYLE 25-10 
BKM_QUERYPAGEWINDOWHWND 25-10 
BKM_QUERYST ATUSLINETEXT 25-11 
BKM_QUERYT ABBITM AP 25-12 
BKM_QUERYT ABTEXT 25-12 
BKM_SETDIMENSIONS 25-13 
BKM_SETNOTEBOOKCOLORS 25-14 
BKM_SETPAGEDAT A 25-14 
BKMSETPAGEWINDOWHWND 25-15 
BKM_SETSTATUSLINETEXT 25-16 
BKM_SETTABBITMAP 25-16 
BKMSETT ABTEXT 25-17 
BKM_TURNTOPAGE 25-18 
BKS_* values 25-1 
BMSG_* values 8-20 
BM_CLICK 13-5 
BM_QUERYCHECK 13-6 
BM_QUERYCHECKINDEX 13-6 
BM_QUERYHILITE 13-7 
BM_SETCHECK 13-7 
BMSETDEFAULT 13-8 
BM_SETHILITE 13-9 
BM_* values 5-232, 5-415 
BN_* values 13-3 
BOOKTEXT A-9 
BOOKTEXT data structure A-9 
BOOL A-9 
Box 5-28 
draw 5-28 

Box at Current Position 33-8 

Box at Given Position 33-8 

Broadcast Message 8-20 

BS_* values 13-1 

BTNCDATA A-9 

button control data 13-2 

button control styles 13-1 

button control window processing 13-1 

button filtering constants 8-183 

BYTE A-10 


c 

C language 1-1 

Calculate Frame Rectangle 8-22 
Call Message Filter 8-24 
Call Segment 33-9 
Call Segment Matrix 5-31 
Cancel Shutdown 8-26 
CAPS_* values 2-15 
CATCHBUF A-10 
CA_* values A-17 

column headings A-19 
drawing and painting A-18 
icons or bit maps A-17 
ordered target emphasis A-18 
title attributes A-18 
title position A-18 
titles A-18 

CBB_* values 5-404, 5-462 
CBM_HILITE 19-5 
CBMJSLISTSHOWING 19-5 
CBM_SHOWLIST 19-6 
CBM_* values 5-71 
CBN_* values 19-3 
CBS_* values 19-1 
CCS_* values 

selection types 24-3 
styles 24-2 
CDATE A-10 
CELL A-10 
CFA_* values A-39 

column attributes A-40 
data types A-39 

horizontal column heading position A-41 
horizontal data position A-40 
icon or bit map data A-40 
prevention of direct editing of a column 
heading A-40 

vertical column heading position A-40 
vertical data position A-40 
CFI_* flags 8-310 
CFI_* values 8-449 
CF_* values 8-449, 28-4 
chain 

draw 5-117 

chained attribute for segments 

modify (GpiSetSegmentAttrs) 5-539 
Change Focus Window 8-160 
Change Switch Entry 8-28 
CHAR A-10 
character 

convert to uppercase 8-558 

query angle 5-244 

query box 5-246 

query break extra 5-248 

query direction 5-249 

query extra 5-250 

query mode 5-251 

query set 5-252 

query shear 5-253 

query string positions 5-255 

query string positions at 5-257 

set angle 5-427 

set box 5-430 

set break extra 5-433 

set direction 5-435 

set extra 5-438 
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character (continued) 
set mode 5-440 
set set 5-443 
set shear 5-445 

character attribute values 5-404, 5-462 
character definitions 
font F-3 

character direction 
Arabic text 5-435 
Chinese text 5-435 
Roman text 5-435 
character set 1-6 
Character String 5-34 

draw at current position 5-34 
draw at current position, with controls 5-39 
draw at specified position 5-36 
draw string at specified position, with controls 5-42 
Character String At 5-36 
Character String at Current Position 33-9 
Character String at Given Position 33-9 
Character String Extended at Current Position 33-10 
Character String Extended at Given Position 33-10 
Character String Move at Current Position 33-1 1 
Character String Move at Given Position 33-11 
Character String Position 5-39 
Character String Position At 5-42 
CHARBUNDLE A-11 
CHDIRNj* values 5-249, 5-435 
check box 13-1 
Check Menu Item 8-32 
Check Message Filter Hook 10-5 
CheckMsgFilterHook 10-5 
Chinese text 5-435 
CHS_* values 5-39, 5-42, 5-255, 5-257 
class 9-1 

CLASSDETAILS A-12 
CLASSINFO A-11 
clipboard 28-1 
messages 28-1 
query format information 8-310 
query viewer window 8-313 
set data 8-449 
clipboard messages 28-1 
clipping 5-528, G-1 

segment chains 5-122 
set path 5-448 
set region 5-451 
clipping boundary 5-486 
clipping region 8-150 
Close Clipboard 8-34 
Close Device Context 2-2 
Close Figure 5-45, 33-12 
Close Profile 6-2 
Close Segment 5-47 
closed figure 5-20 

CLR_* values 5-76, 5-23 1 , 5-262, 5-338, 5-412, 5-453 
CMDSRC_* values 11-3, 12-27, 12-36, 12-63, 15-21 
CM_ALLOCDETAILFIELDINFO 24-22 
CM_ALLOCRECORD 24-23 
CM_ARRANGE 24-24 
CM_CLOSEEDIT 24-24 
CM_COLLAPSETREE 24-25 
CM_ERASERECORD 24-26 
CM_EXPANDTREE 24-26 
CM_FILTER 24-27 
CM_FREEDETAILFIELDINFO 24-28 
CM FREERECORD 24-29 


CM_HORZSCROLLSPLITWINDOW 24-30 
CMJNSERTDETAILFIELDINFO 24-30 
CMJNSERTRECORD 24-31 
CMJNVALIDATEDETAILFIELDINFO 24-33 
CMJNVALIDATERECORD 24-33 
CMJDPENEDIT 24-35 
CM_PAINTBACKGROUND 24-35 
CM_QUERYCNRINFO 24-36 
CM_QUERYDETAILFIELDINFO 24-37 
CM_QUERYDRAGIMAGE 24-38 
CM_QUERYRECORD 24-39 
CM_QUERYRECORDEMPHASIS 24-40 
CM_QUERYRECORDFROMRECT 24-41 
CM_QUERYRECORDINFO 24-42 
CM_QUERYRECORDRECT 24-43 
CM_QUERYVIEWPORTRECT 24-43 
CM_REMOVEDETAILFIELDINFO 24-44 
CM_REMOVERECORD 24-45 
CM_SCROLLWINDOW 24-47 
CM_SEARCHSTRING 24-48 
CM_SETCNRINFO 24-49 
CM_SETRECORDEMPHASIS 24-50 
CM_SORTRECORD 24-51 
CM_* values 5-251, 5-427, 5-440 
CNRDRAGINFO A-12 
CNRDRAGINIT A-12 
CNRDRAWITEMINFO A-13 
CNREDITDATA A-14 
CNREDITDATA data structure A-13 
CNRINFO A-15 
CN_BEGINEDIT 24-8 
CN_COLLAPSETREE 24-9 
CN_CONTEXTMENU 24-9 
CN_DRAGAFTER 24-10 
CN_DRAGLEAVE 24-11 
CN_DRAGOVER 24-12 
CN_DROP 24-13 
CN_DROPHELP 24-14 
CN_EMPHASIS 24-15 
CN_ENDEDIT 24-15 
CN_ENTER 24-16 
CN_EXPANDTREE 24-17 
CNJHELP 24-17 
CNJNITDRAG 24-18 
CN_KILLFOCUS 24-19 
CN_QUERYDELT A 24-19 
CN_REALLOCPSZ 24-20 
CN_SCROLL 24-21 
CN_SETFOCUS 24-21 
CN_* values 

described 24-8 
code page 
query 8-314 
set 8-456 

Code Page Change Hook 10-7 
Code pages 34-1 
ASCII 34-11 
EBCDIC 34-16 
Font support 34-4 
OS/2 options for PM 34-3 
OS/2 support for multiple 34-4 
CodePageChangeHook 10-7 
COLOR A-20 
color palette 8-362 
color table G-1 
create 5-74 

color table default values 5-76 
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colors 

on monochrome devices 5-76 

query 5-262 

query data 5-264 

query foreground mix mode 5-324 

query index 5-266 

query nearest 5-327 

query real 5-343 

query RGB 5-349 

query system 8-362 

set 5-453 

set background 5-412 
set system values 8-494 
Combine Region 5-49 
combo box control data 19-1 
combo box control window processing 19-1 
Comment 5-51, 33-12 
Compare Strings 8-35 
constant names 1-1 
constants 

button filtering 8-183 
container control window processing 
data structures 24-3 
icon size, how determined A-17 
mini-icon size, how determined A-17 
notification codes 24-8 
notification messages 24-4 
purpose 24-1 

styles and selection types 24-2 
window messages 24-22 
window words 24-1 
container views A-16 

contents and format of dialog template 32-19 
control classes 11-2 
control codes 

Shift In (SI) 34-23 
Shift Out (SO) 34-23 
control data 32-22 
Control Formatting 4-35 
control statements 
predefined 32-24 
control window processing 11-2 
CONVCONTEXT A-20 
conventions 
Convert 5-53 
Convert with Matrix 5-55 
coordinates 
dialog 32-19 

coordinates for dialogs 32-19 
Copy Accelerator Table 8-37 
Copy Metafile 5-57 
Copy Rectangle 8-39 
Correlate Chain 5-59 
Correlate From 5-63 
Correlate Segment 5-67 
cosmetic line width 
query 5-311 

Counts Number of Items in Listbox 8-330 
CPTEXT A-21 

Create a Paragraph in DDF Buffer 4-24 

Create Accelerator Table 8-44 

Create Atom Table 8-46 

Create Bit Map 5-71 

Create Cursor 8-48 

Create Dialog 8-50 

Create Frame Controls 8-52 

Create Help Instance 8-54 


Create Help Table 8-56 
Create Logical Color Table 5-74 
Create Logical Font 5-78 
Create Menu 8-58 
Create Message Queue 8-60 
Create Palette 5-81 
Create Pointer 8-64 
Create Pointer Indirect 8-66 
Create Presentation Space 5-84 
Create Region 5-88 
Create Standard Window 8-68 
Create String Handle 3-5 
Create Switch Entry 8-72 
Create Window 8-74 
Create Workplace Object 8-62 
CREATESTRUCT A-21 
CREA_* values 5-195 
CRGN_* values 5-49 
CS_* values 

window class styles 12-1 
CTAB_* values 5-195 
CTIME A-22 
current position 
move 5-173 
query 5-269 

set to specified point 5-458 
cursor 

create 8-48 
destroy 8-101 
hide 8-518 

query information 8-316 
show 8-518 
CURSORINFO A-22 
CURSOR_* values 8-48 
CVR_* values 12-23 
CVTC_* values 5-53 
CV_* values 

CNRINFO structure A-16 
SEARCHSTRING structure A-115 
view styles A-17 

D 

data 

bit map D-1 
get 5-150 
put 5-223 

data area in a dialog template 32-22 
data format 
image F-7 
outline F-8 
data types A-1 

graphics orders 33-1 
implicit pointer 1-5 
storage mapping 1-6 
DBCS 8-285 
DBCS support 34-23 

character-encoding schemes 34-23 
DBM_* values 8-118 
DB_* values 8-121 
DCTL_* values 5-282, 5-474 
DC_* values A-32 
DDEF_* values 5-195 
DDEINIT A-23 
DDESTRUCT A-23 
DDE_* values 30-1 , 30-2, 30-3, A-23 
DdfBeginList 4-2 
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DdfBitmap 4-5 
DdfEndList 4-8 
Ddf HyperText 4-10 
Ddflnform 4-13 
Ddflnitialize 4-15 
DdfListltem 4-18 
DdfMetafile 4-21 
DdfPara 4-24 
DdfSetColor 4-26 
DdfSetFont 4-29 
DdfSetFontStyle 4-32 
DdfSetFormat 4-35 
DdfSetTextAlign 4-37 
DdfText 4-39 

default colors 13-2, 14-2, 15-3, 16-1, 17-3, 19-2, 20-2, 
22-2, 23-1 

Default Dialog Procedure 8-85 
default dialog processing 12-70 
default graphics character box 
query 5-275 

default message processing 12-1 
default view matrix 
query 5-273 

Default Window Procedure 8-89 
default window processing 1 1-1 
DEFAULTICON keyword 32-11 
Define Hypertext Link 4-10 
Define Inform Link 4-13 
Define Text Alignment 4-37 
Delete Atom 8-91 
Delete Bit Map 5-90 
Delete DRAGINFO String Handles 3-10 
Delete Element 5-92 
Delete Element Range 5-94 
Delete Elements Between Labels 5-96 
Delete Library 8-95 
Delete Listbox Item 8-93 
Delete Metafile 5-98 
Delete Palette 5-100 
Delete Procedure 8-96 
Delete Segment 5-102 
Delete Segments 5-104 
Delete Set Identifier 5-106 
Delete String Handle 3-11 
DELETENOTIFY A-24 
Deregister Workplace Object Class 8-97 
DESKTOP A-24 
Destroy Accelerator T able 8-98 
Destroy Atom Table 8-99 
Destroy Cursor 8-101 
Destroy Help Instance 8-102 
Destroy Message Queue 8-104 
Destroy Pointer 8-107 
Destroy Presentation Space 5-108 
Destroy Region 5-110 
Destroy Window 8-109 
Destroy Window Hook 10-8 
Destroy Workplace Object 8-106 
DestroyWindowHook 10-8 
detectability attribute for segments 
modify (GpiSetSegmentAttrs) 5-539 
DevCIoseDC 2-2 
DevEscape 2-4 
DEVESC_* values 2-4, 2-5 
device characteristics 
query 2-15 
device context 


device context (continued) 
clear output display 5-136 
close 2-2 
create 2-9 
open 2-9 

open for a window 8-273 
screen 8-128 
DevOpenDC 2-9 
DEVOPENSTRUC A-25 
DevPostDeviceModes 2-12 
DevQueryCaps 2-15 
DevQueryDeviceNames 2-21 
DevQueryHardcopyCaps 2-24 
DEV_* values 2-2,2-10 
DFORM_* values 5-150, 5-223 
dialog 

create 8-50 
default procedure 8-85 
dismiss 8-111 
enumerate item 8-145 
load 8-236 
process modal 8-287 
query item short 8-321 
send message to item 8-435 
set item short 8-459 
dialog item 

query text 8-323 
query text length 8-325 
set text 8-461 
dialog points 
map 8-259 

Dialog Procedure 10-2 
dialog processing 12-70 
default 12-70 
language support 12-83 
dialog template 

data-area information 32-22 
format and contents 32-19 
header information 32-20 
item information 32-21 
dialog window 

destroy modal 8-111 
hide modeless 8-111 
DialogProc 10-2 
dialogs 

define procedure 10-2 
Direct Manipulation for Files 3-2 
direct manipulation messages 29-1 
directives 32-4 
Dismiss Dialog 8-111 
Dispatch Message 8-113 
dithered colors 5-327 
dithering 5-327, 8-494 
DLGC_* values 12-72 
DLGTEMPLATE A-27 
DLGTEM PLATE statement 32-16 
DLGTITEM A-27 
DM_DISCARDOBJECT 29-1 
DM_DRAGERROR 29-2 
DM_DRAGFILECOMPLETE 29-2 
DM_DRAGLEAVE 29-3 
DM_DRAGOVER 29-4 
DM_DRAGOVERNOTIFY 29-5 
DM_DROP 29-6 
DM_DROPHELP 29-7 
DM_EMPHASIZET ARGET 29-7 
DM ENDCONVERSATION 29-8 



DM_FILERENDERED 29-9 
DM_PRINTOBJECT 29-9 
DM_RENDER 29-10 
DM_RENDERCOMPLETE 29-11 
DM_RENDERFILE 29-12 
DM_RENDERPREPARE 29-13 
DM_* values 5-284, 5-477 
double-byte character set 1-6 
double-byte character sets 34-23 
Down cursor key 8-547 
DO_* values 

DRAGINFO data structure A-29 

DRAGITEM data structure A-32 
DPC errors 5-2 
DPDM_* values 2-13 
DP * values 8-124 
Drag 3-12 
drag Information 

access 3-4 
drag messages 29-1 
DRAGIMAGE A-28 
DRAGINFO A-29 
DRAGITEM A-30 
DRAGTRANSFER A-32 
Draw Bit Map 8-118 
Draw Bits 5-112 
Draw Border 8-121 
Draw Chain 5-117 
Draw Dynamics 5-119 
Draw From 5-121 
draw mode 5-47 
Draw Pointer 8-124 
Draw Polygons 5-207 
Draw Segment 5-123 
Draw Text 8-126 
Draw Tracking Rectangle 8-546 
draw-and-retain mode 5-47 
drawing mode 

draw 5-126, 5-474, 5-478, 5-558 

draw-and-retain 5-126, 5-287, 5-474, 5-478, 5-558 

query 5-284 

retain 5-126, 5-252, 5-287, 5-478, 5-558 

set 5-477 

drawing orders 33-1 
drawing process check errors 5-2 
DRF_* values A-31 
DrgAcceptDroppedFiles 3-2 
DrgAccessDraginfo 3-4 
DrgAddStrHandle 3-5 
DrgAllocDraginfo 3-7 
DrgAllocDragtransfer 3-9 
DrgDeleteDraginfoStrHandles 3-10 
DrgDeleteStrHandle 3-11 
DrgDrag 3-12 
DrgDragFiles 3-16 
DrgFreeDraginfo 3-19 
DrgFreeDragtransfer 3-21 
DrgGetPS 3-22 
DrgPostTransferMsg 3-24 
DrgPushDraginfo 3-26 
DrgQueryDragitem 3-28 
DrgQueryDragitemCount 3-30 
DrgQueryDragitemPtr 3-31 
DrgQueryNativeRMF 3-32 
DrgQueryNativeRMFLen 3-34 
DrgQueryStrName 3-36 
DrgQueryStrNameLen 3-38 


DrgQueryTrueType 3-40 

DrgQueryTrueTypeLen 3-42 

DrgReleasePS 3-44 

DrgSendTransferMsg 3-45 

DrgSetDraglmage 3-48 

DrgSetDragitem 3-50 

DrgSetDragPointer 3-53 

DrgVerifyNativeRMF 3-55 

DrgVerifyRMF 3-57 

DrgVerifyTrueType 3-59 

DrgVerifyType 3-61 

DrgVerifyTypeSet 3-63 

DRG_* values A-29 

DRIVDATA A-33 

DRIVPROPS A-34 

DRM_* values A-31 

DRO_* values 5-28, 5-148 

DRT_* values A-30 

DTYP_* values 8-408 

DT_* values 8-127, 22-1 

Dynamic Data Exchange Initiate (NLS) 8-78 

dynamic data exchange messages 30-1 

Dynamic Data Exchange Post Message (NLS) 8-80 

Dynamic Data Exchange Respond (NLS) 8-83 

E 

EBCDIC MIXED code pages 34-23 
edit mode 

query 5-285 
set 5-480 
EDI_* values 8-145 
EGA 2-19 
Element 5-125 
end 5-130 
query 5-286 
elements 

delete 5-92 

delete between labels 5-96 
delete between range 5-94 
offset pointer 5-177 
query pointer 5-288 
query type 5-290 
set pointer at label 5-484 
Empty Clipboard 8-130 
EM_CLEAR 14-4 
EM_COPY 14-4 
EM_CUT 14-5 
EM_PASTE 14-5 
EM_QUERYCHANGED 14-6 
EM_QUERYFIRSTCHAR 14-7 
EMQUERYREADONLY 14-7 
EM_QUERYSEL 14-8 
EM_SETFIRSTCHAR 14-8 
EM_SETINSERTMODE 14-9 
EM_SETREADONLY 14-10 
EM_SETSEL 14-10 
EM_SETTEXTLIM IT 14-11 
Enable Control of Button Id 8-131 
Enable Menu Item 8-132 
Enable Physical Input 8-134 
Enable Window Update 8-137 
encapsulation 9-1 
End Area 5-128, 33-13 
End Definition List 4-8 
End Element 5-130, 33-13 
End Image 33-13 
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End of Symbol Definition 33-14 

End Paint 8-141 

End Path 5-132,33-14 

End Prolog 33-14 

End Window Enumeration 8-139 

ENDFONT structure F-1 

Enter key 8-547 

entry field control data 14-2 

entry field control window processing 14-1 

ENTRYFDATA A-34 

Enumerate Clipboard Formats 8-143 

Enumerate Dialog Item 8-145 

Enumerate Object Classes 8-147 

EN_* values 14-3, 18-3 

EQRGN_* values 5-134 

Equal Rectangle 8-148 

Equal Region 5-134 

Erase 5-136 

ERRINFO A-35 

Error Segment Data 5-138 

error severities 1-2 

error state 

get last one 8-178 
error-information block 8-165 
ERRORID A-35 
errors 

codes B-1 

drawing process check 5-2 
explanations C-1 
get information 8-175 
severities of 1-2 
Esc key 8-547 
Escape 2-4, 33-15 
ESCSETMODE A-35 
ES_* dbcsvals 14-2 
ES_* values 14-1 
Exclude Clip Rectangle 5-140 
Exclude Update Region 8-150 
Extended Escape 33-15 

F 

FACENAMEDESC A-35 
FATTRS A-36 

FATTR_FONTUSE_* values A-38 

FATTR_SEL_* values A-37 

FATTR_TYPE_* values A-38 

FCF_* frame styles 8-424 

FCF_* values 15-1 

FC_* values 8-160 

FDATE A-38 

FDM_ERROR 12-73 

FDMFILTER 12-74 

FDM_ VALIDATE 12-74 

FDS_* values A-42 

FFDESCS A-39 

FFDESCS2 A-39 

FF_* indicators 8-400 

FF_* values 5-144 

FID_* values 15-1, 23-1 

FIELDINFO A-39 

FIELDINFOINSERT A-41 

FIELDINFOINSERT data structure A-41 

file dialog 12-73 

file format 

file formats 

bit maps D-2 


file formats (continued) 
icon file D-2 
pointer D-2 
FILEDLG A-42 
FILEFINDBUF4 A-46 
Fill Path 5-142,33-16 
Fill Rectangle 8-154 
Fillet at Current Position 33-16 
Fillet at Given Position 33-16 
Find Atom 8-156 
Find Word Hook 10-9 
FindWordHook 10-9 
FIXED A-46 
Fl_* values 15-18 
Flash Window 8-158 
flashing 

start 8-158 
stop 8-158 
flipping bits 8-211 
Flood Fill 5-144 
FM_* values 5-324, 5-510 
FNTF_* values A-49 
FNTM_FACENAMECHANGED 12-76 
FNTM_FILTERLIST 12-77 
FNTM_POINTSIZECHANGED 12-78 
FNTM_STYLECHANGED 12-78 
FNTM_UPDATEPREVIEW 12-79 
FNTS_* values A-48 
FOCAMETRICS structure F-2 
focus 

change window 8-160 
query 8-327 
set window 8-464 
FOLDERDATA A-46 
font character definitions F-3 
font definition header F-4 
font dialog 12-75 
font directory F-1 1 
font metrics F-1 
font-file format F-1 

FONTDEFINITIONHEADER structure F-4 
FONTDLG A-47 
FONTMETRICS A-52 
fonts 

create logical definition 5-78 
definition of terms F-12 
Japanese 34-23 
load 5-163 
load public 5-167 

outline 5-427, 5-430, 5-433, 5-438, 5-445 
query 5-299 
query action 5-294 
query face string 5-292 
query logical 5-315 
query metrics 5-297 
query number of local identifiers 5-329 
query set identifiers 5-359 
query width table 5-372 
raster 5-427, 5-430, 5-433, 5-438, 5-445, 5-522 
unload 5-563 
unload public 5-565 
fonts supplied with OS/2 E-1 
FONTSIGNATURE structure F-1 
FONT_* values 5-78 
format 

font-file F-1 

format and contents of dialog template 32-19 
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FPATH_* values 5-142, 5-191 
frame control data 15-3 
frame control window processing 15-1 
Frame Region 5-146 
FRAMECDATA A-60 
Free DRAGINFO Structure 3-19 
Free DRAGTRANSFER Storage 3-21 
Free Error Information 8-165 
Free File Icon 8-168 
Free Standard File Dialog File List 8-166 
FS_* values 15-3 
FTIME A-61 
Full Arc 5-148 
create 5-148 

Full Arc at Current Position 33-17 
Full Arc at Given Position 33-17 
function descriptions 
conventions used 1-1 
functions 

supplied by applications 10-1 


G 

GARC 33-3 

GBAR 33-3 

GBBLT 33-7 

GBEL 33-4 

GBEZ 33-6 

GBIMG 33-5 

GBIT1 33-1 

GBIT16 33-1 

GBIT2 33-1 

GBIT32 33-1 

GBIT4 33-1 

GBIT5 33-1 

GBIT6 33-1 

GBIT7 33-1 

GBIT8 33-1 

GBOX 33-8 

GBPTH 33-5 

GCALLS 33-9 

GCARC 33-3 

GCBEZ 33-6 

GCBIMG 33-5 

GCBOX 33-8 

GCCHST 33-9 

GCCHSTE 33-10 

GCCHSTM 33-11 

GCFARC 33-17 

GCFLT 33-16 

GCHAR 33-1 

GCHST 33-9 

GCHSTE 33-10 

GCHSTM 33-11 

GCLFIG 33-12 

GCLINE 33-18 

GCMRK 33-18 

GCOMT 33-12 

GCPARC 33-20 

GCRLINE 33-22 

GCSFLT 33-50 

GDELPOINT 33-1 

GEAR 33-13 

GEEL 33-13 

GEESCP 33-15 

GEIMG 33-13 

general window styles 12-1 


geometric line width 5-312 
GEPROL 33-14 
GEPTH 33-14 
GESCP 33-15 
GESD 33-14 

Get Clipped Presentation Space 8-169 
Get Current Time 8-171 
Get Data 5-150 
Get Dialog Message 8-172 
Get Drag Presentation Space 3-22 
Get Dragged Object Count 3-30 
Get DRAGITEM Structure 3-28 
Get Error Information 8-175 
Get Format of a Dragged Object 3-32 
Get Key State 8-176 
Get Last Error 8-178 
Get Maximum Position 8-179 
Get Message 8-183 
Get Minimum Position 8-181 
Get Multiple Windows From Identities 8-266 
Get Next Window 8-186 
Get Physical Key State 8-188 
Get Pointer to DRAGITEM Structure 3-31 
Get Presentation Space 8-190 
Get Screen Presentation Space 8-192 
Get String Contents 3-36 
Get String Length 3-38 
Get String Length for Native RMF of Dragged 
Object 3-34 

Get String Length for True Type of Dragged Object 3-42 

Get System Bit Map 8-194 

Get True Type of Dragged Object 3-40 

GFARC 33-17 

GFIXED 33-2 

GFIXEDS 33-2 

GFLT 33-16 

GFPTH 33-16 

GHBITMAP 33-2 

GIMD 33-17 

GINDATT 33-2 

GINDEX3 33-2 

GLBL 33-18 

GLENGTH1 33-2 

GLENGTH2 33-2 

GLINE 33-18 

GLONG 33-2 

GMPTH 33-19 

GMRK 33-18 

GNOP1 33-19 

GOPTH 33-19 

GPARC 33-20 

GpiAnimatePalette 5-8 

GpiAssociate 5-11 

GpiBeginArea 5-13 

GpiBeginElement 5-17 

GpiBeginPath 5-19 

GpiBitBIt 5-23 

GpiBox 5-28 

GpiCallSegmentMatrix 5-31 
GpiCharString 5-34 
GpiCharStringAt 5-36 
GpiCharStringPos 5-39 
GpiCharStringPosAt 5-42 
GpiCloseFigure 5-45 
GpiCloseSegment 5-47 
GpiCombineRegion 5-49 
GpiComment 5-51 
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GpiConvert 5-53 
GpiConvertWithMatrix 5-55 
GpiCopyMetaFile 5-57 
GpiCorrelateChain 5-59 
GpiCorrelateFrom 5-63 
GpiCorrelateSegment 5-67 
GpiCreateBitmap 5-71 
GpiCreateLogColorTable 5-74 
GpiCreateLogFont 5-78 
GpiCreatePalette 5-81 
GpiCreatePS 5-84 
GpiCreateRegion 5-88 
GpiDeleteBitmap 5-90 
GpiDeleteElement 5-92 
GpiDeleteElementRange 5-94 
GpiDeleteElementsBetweenLabels 5-96 
GpiOeleteMetaFile 5-98 
GpiDeletePalette 5-100 
GpiDeleteSegment 5-102 
GpiDeleteSegments 5-104 
GpiDeleteSetld 5-106 
GpiDestroyPS 5-108 
GpiDestroyRegion 5-110 
GpiDrawBits 5-112 
GpiDrawChain 5-117 
GpiDrawDynamics 5-119 
GpiDrawFrom 5-121 
GpiDrawSegment 5-123 
GpiElement 5-125 
GpiEndArea 5-128 
GpiEndElement 5-130 
GpiEndPath 5-132 
GpiEqualRegion 5-134 
GpiErase 5-136 
GpiErrorSegmentData 5-138 
GpiExcludeClipRectangle 5-140 
GPIE_* values 5-138 
GpiFillPath 5-142 
GpiFloodFill 5-144 
GpiFrameRegion 5-146 
GpiFullArc 5-148 
GPIF_* values 5-533 
GpIGetData 5-150 
Gpllmage 5-153 
GpilntersectClipRectangle 5-155 
GpiLabel 5-157 
GpiLine 5-159 
GpiLoadBitmap 5-161 
GpiLoadFonts 5-163 
GpILoadMetaFile 5-165 
GpILoadPubllcFonts 5-167 
GpiMarker 5-168 
GpiModlfyPath 5-170 
GpiMove 5-173 
GplOffsetClipRegion 5-175 
GpiOffsetElementPoinler 5-177 
GpiOttsetRegion 5-179 
GplOpenSegment 5-181 
GplOutllnePath 5-184 
GpIPalntReglon 5-186 
GpIPartlalArc 5-188 
GpiPathToRegion 5-191 
GpIPlayMetaFile 5-193 
GpiPointArc 5-199 
GpiPolyFillet 5-201 
GpiPolyFilletSharp 5-204 
GpiPolygons 5-207 


GpiPolyLlne 5-209 
GpiPolyLlneDisjoInt 5-211 
GpiPolyMarker 5-213 
GpiPolySpline 5-215 
GpiPop 5-217 
GpiPtlnRegion 5-219 
GpiPtVisible 5-221 
GpIPutData 5-223 
GpIQueryArcParams 5-226 
GpIQueryAttrMode 5-228 
GpiQueryAttrs 5-229 
GpIQueryBackColor 5-231 
GpiQueryBackMix 5-232 
GpiQueryBItmapBits 5-233 
GpIQueryBItmapOimenslon 5-236 
GpIQueryBItmapHandle 5-239 
GpiQueryBitmapInfoHeader 5-237 
GpIQueryBitmapParameters 5-240 
GpIQueryBoundaryData 5-242 
GpiQueryCharAngle 5-244 
GpIQueryCharBox 5-246 
GpIQueryCharBreakExtra 5-248 
GpIQueryCharDirection 5-249 
GpiQueryCharExtra 5-250 
GpiQueryCharMode 5-251 
GpIQueryCharSet 5-252 
GpIQueryCharShear 5-253 
GpiQueryCharStringPos 5-255 
GpIQueryCharStringPosAt 5-257 
GpIQueryClIpBox 5-259 
GpiQueryClipRegion 5-261 
GpIQueryColor 5-262 
GpIQueryColorData 5-264 
GpiQueryColorlndex 5-266 
GpiQueryCp 5-268 
GpIQueryCurrentPosition 5-269 
GpiQueryDefArcParams 5-270 
GpIQueryDefAttrs 5-271 
GpIQueryOefauItViewMatrix 5-273 
GpiQueryDefCharBox 5-275 
GpiQueryDefTag 5-277 
GpiQueryDefVlewIngLimits 5-278 
GpIQueryDevIce 5-279 
GpiQueryDeviceBitmapFormats 5-280 
GpiQueryDrawControl 5-282 
GpiQueryDrawingMode 5-284 
GpiQueryEditMode 5-285 
GpIQueryElement 5-286 
GpiQueryElementPointer 5-288 
GpiQueryElementType 5-290 
GpIQueryFaceString 5-292 
GpIQueryFontAction 5-294 
GpiQueryFontFlleOescrlptions 5-295 
GpiQueryFontMetrics 5-297 
GpIQueryFonts 5-299 
GpiQueryFullFontFileDescrlptions 5-301 
GpiQueryGraphlcsFleld 5-303 
GpIQuerylnltialSegmentAttrs 5-304 
GpIQueryKernlngPalrs 5-306 
GpiQueryLlneEnd 5-308 
GpiQueryLlneJoln 5-309 
GpiQueryLineType 5-310 
GpiQueryLlneWldth 5-311 
GpIQueryLlneWldthGeom 5-312 
GpIQueryLogColorTable 5-313 
GpiQueryLoglcalFont 5-315 
GpiQueryMarker 5-317 
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GpiQueryMarkerBox 5-318 
GpiQueryMarkerSet 5-320 
GpiQueryMetaFileBits 5-321 
GpiQueryMetaFileLength 5-323 
GpiQueryMix 5-324 
GpiQueryModelT ransformMatrix 5-325 
GpiQueryNearestColor 5-327 
GpiQueryNumberSetlds 5-329 
GpiQueryPageViewport 5-330 
GpiQueryPalette 5-332 
GpiQueryPalettelnfo 5-333 
GpiQueryPattern 5-335 
GpiQueryPatternRefPoint 5-336 
GpiQueryPalternSet 5-337 
GpiQueryPel 5-338 
GpiQuery PickApertu rePosit ion 5-340 
GpiQueryPickApertureSize 5-341 
GpiQueryPS 5-342 
GpiQueryRealColors 5-343 
GpiQueryRegionBox 5-345 
GpiQueryRegionRects 5-347 
GpiQueryRGBColor 5-349 
GpiQuerySegmentAttrs 5-351 
GpiQuerySegmentNames 5-353 
GpiQuerySegmentPriority 5-355 
GpiQuerySegmenlT ransformMatrix 5-357 
GpiQuerySetlds 5-359 
GpiQueryStopDraw 5-362 
GpiQueryTag 5-363 
GpiQueryTextAlignment 5-364 
GpiQueryTextBox 5-365 
GpiQueryViewingLimits 5-368 
GpiQueryViewingT ransformMatrix 5-370 
GpiQuery WidthTable 5-372 
GpiRectlnRegion 5-374 
GpiRectVisible 5-376 
GpiRemoveDynamics 5-378 
GpiResetBoundaryData 5-381 
GpiResetPS 5-382 
GpiRestorePS 5-384 
GpiRotate 5-386 
GpiSaveMetaFile 5-389 
GpiSavePS 5-391 
GpiScale 5-393 
GpiSelectPalette 5-396 
GpiSetArcParams 5-398 
GpiSetAttrMode 5-401 
GpiSetAttrs 5-404 
GpiSetBackColor 5-412 
GpiSetBackMix 5-415 
GpiSetBitmap 5-418 
GpiSetBitmapBits 5-420 
GpiSetBitmapDimension 5-423 
GpiSetBitmapid 5-425 
GpiSetCharAngle 5-427 
GpiSetCharBox 5-430 
GpiSetCharBreakExtra 5-433 
GpiSetCharDirection 5-435 
GpiSetCharExtra 5-438 
GpiSetCharMode 5-440 
GpiSetCharSet 5-443 
GpiSetCharShear 5-445 
GpiSetClipPath 5-448 
GpiSetClipRegion 5-451 
GpiSetColor 5-453 
GpiSetCp 5-456 
GpiSetCurrentPosition 5-458 


GpiSetDefArcParams 5-460 
GpiSetDefAttrs 5-462 
GpiSetDefauitViewMatrix 5-467 
GpiSetDefTag 5-470 
GpiSetOefViewingLimits 5-472 
GpiSetDrawControl 5-474 
GpiSetDrawingMode 5-477 
GpiSetEditMode 5-480 
GpiSetElementPointer 5-482 
GpiSetElementPointerAtLabel 5-484 
GpiSetGraphicsField 5-486 
GpiSetlnitialSegmentAttrs 5-488 
GpiSetLineEnd 5-491 
GpiSetLineJoin 5-493 
GpiSetLineType 5-495 
GpiSetLineWidth 5-498 
GpiSetLineWidthGeom 5-500 
GpiSetMarker 5-502 
GpiSetMarkerBox 5-504 
GpiSetMarkerSet 5-506 
GpiSetMetaFileBits 5-508 
GpiSetMix 5-510 

GpiSetModelTransformMatrix 5-513 
GpiSetPageViewport 5-516 
GpiSetPaletteEntries 5-518 
GpiSetPattern 5-521 
GpiSetPatternRefPoint 5-524 
GpiSetPatternSet 5-526 
GpiSetPel 5-528 

GpiSetPickAperturePosition 5-530 

GpiSetPickApertureSize 5-531 

GpiSetPS 5-533 

GpiSetRegion 5-536 

GpiSetSegmentAttrs 5-538 

GpiSetSegmentPriority 5-541 

GpiSetSegmentTransformMatrix 5-543 

GpiSetStopDraw 5-546 

GpiSetTag 5-548 

GpiSetTextAlignment 5-550 

GpiSetViewingLimits 5-553 

GpiSetViewingTransformMatrix 5-555 

GpiStrokePath 5-558 

GpiTranslate 5-560 

GpiUnloadFonts 5-563 

GpiUnloadPublicFonts 5-565 

GpiWCBitBIt 5-567 

GPI_* values 5-196 

GPOINT 33-2 

GPOINTB 33-2 

G POLYS 33-2,33-20 

GPOP 33-21 

GPSAP 33-23 

GPSBCOL 33-23 

GPSBICOL 33-24 

GPSBMX 33-25 

GPSCA 33-26 

GPSCBE 33-26 

GPSCC 33-27 

GPSCD 33-28 

GPSCE 33-28 

GPSCH 33-30 

GPSCOL 33-31 

GPSCP 33-32 

GPSCR 33-29 

GPSCS 33-30 

GPSECOL 33-32 

GPSFLW 33-33 
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GPSIA 33-35 
GPSICOL 33-34 
GPSLE 33-36 
GPSLJ 33-36 
GPSLT 33-37 
GPSLW 33-38 
GPSMC 33-39 
GPSMP 33-40 
GPSMS 33-40 
GPSMT 33-41 
GPSMX 33-41 
GPSPIK 33-45 
GPSPRP 33-43 
GPSPS 33-44 
GPSPT 33-44 
GPSSLW 33-46 
GPSTA 33-47 
GPSTM 33-42 
GPSVW 33-48 
GRADIENTL A-61 
graphics 

orders 33-1 
query field 5-303 
set field 5-486 
graphics orders 
data types 33-1 
GREAL 33-2 
GRES_* values 5-382 
GRUNE 33-22 
GROF 33-2 
GROFUFS 33-2 
GROL 33-2 
GROSOL 33-2 
GROUFS 33-2 
GROUL 33-2 
GSAP 33-23 
GSBCOL 33-23 
GSBICOL 33-24 
GSBMX 33-25 
GSCA 33-26 
GSCBE 33-26 
GSCC 33-27 
GSCD 33-28 
GSCE 33-28 
GSCH 33-30 
GSCOL 33-31 
GSCP 33-32 
GSCPTH 33-31 
GSCR 33-29 
GSCS 33-30 
GSECOL 33-32 
GSFLT 33-50 
GSFLW 33-33 
GSGCH 33-22 
GSHORT 33-2 
GSHORT370 33-2 
GSIA 33-35 
GSICOL 33-34 
GSLE 33-36 
GSLJ 33-36 
GSLT 33-37 
GSLW 33-38 
GSMC 33-39 
GSMP 33-40 
GSMS 33-40 
GSMT 33-41 
GSMX 33-41 


GSPIK 33-45 
GSPRP 33-43 
GSPS 33-44 
GSPT 33-44 
GSSB 33-45 
GSSLW 33-46 
GST A 33-47 
GSTM 33-42 
GSTR 33-2 
GSTV 33-48 
GSVW 33-48 
GUCHAR 33-2 
GUFIXEDS 33-3 
GULONG 33-3 
GULONG370 33-3 
GUNDF 33-3 
GUNDF1 33-3 
GUSHORT 33-3 
GUSHORT370 33-3 


H 

HAB A-61 

HACCEL A-61 

HAPP A-61 

HATOMTBL A-61 

HBITMAP A-61 

HCAPS_* values A-62 

HCINFO A-61 

HDC A-62 

HDDF A-62 

header 32-20 

header files 1-3 

Help Hook 10-10 

help manager messages 31-1 

helper macros 1-3 

HelpHook 10-10 

HELPINIT A-62 

HELPTABLE A-63 

HENUM A-64 

HEV A-64 

HFILE A-64 

HFIND A-64 

HFM_* values 10-10 

HIGHER,* values 5-355, 5-541 

highlight attribute for segments 

modify (GpiSetSegmentAttrs) 5-539 
HINI A-64 
HK_* values 8-466 
HUB A-64 

HMERR_* error constants 31-4 

HMF A-64 

HMODULE A-64 

HMQ A-64 

HMQ_* values 8-418 

HMTX A-64 

HMUX A-64 

HM_ACTIONBAR_COMMAND 31-1 
HM_CONTROL 31-1 
HM_CREATE_HELP_TABLE 31-2 
HM_DISMISS_WINDOW 31-2 
HM_DISPLAY_HELP 31-3 
HM_ERROR 31-4 
HM_EXT_HELP 31-5 
HM_EXT_HELP_UNDEFINED 31-6 
HM_GENERAL_HELP 31-6 
HM_GENERAL_HELP_UNDEFINED 31-7 
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HM_HELPSUBITEM_NOT_FOUND 31-8 
HM_HELP_CONTENTS 31-7 
HM_HELP_INDEX 31-8 
HMJNFORM 31-9 
HMJNVALIDATE_DDF_DATA 31-10 
HM_KEYS_HELP 31-10 
HM_LOAD_HELP_TABLE 31-11 
HM_NOTIFY 31-12 
HM_QUERY 31-13 
H M_QUE R Y_DDF_D AT A 31-14 
HM_QUERY_KEYS_HELP 31-14 
HM_REPLACE_HELP_FOR_HELP 31-15 
HM_REPLACE_USING_HELP 31-15 
HM_SET_ACTI VE_W I N DO W 31-16 
HM_SET_COVERPAGE_SIZE 31-17 
HM_SET_HELP_LIBRARY_NAME 31-17 
HM_SET_HELP_WINDOW_TITLE 31-18 
HM_SET_OBJCOM_ WINDOW 31-18 
HM_SET_SHOW_PANEL_ID 31-19 
HM_SET_USERDATA 31-19 
HM_TUTORIAL 31-20 

HM_UPDATE_OBJCOM_WINDOW_CHAIN 31-21 

HOBJECT A-64 

hook 

change code page 10-7 
find word 10-9 
help requests 10-10 
input 10-8, 10-13 
message filter 10-20 
release 8-418 
send message 10-23 
set 8-466 
hooks 10-1 
HPAL A-64 
H POINTER A-64 
HPROC A-64 
HPROGARRAY A-64 
H PROGRAM A-65 
HPS A-65 
HRGN A-65 
HRGN_* values 5-451 
HSEM A-65 
HSPL A-65 
HSTR A-65 
HSVWP A-65 
HSWITCH A-65 
HT_* values 12-37 
HWND A-65 

HWND_* values 8-1 1 , 8-50, 8-52, 8-58, 8-115, 8-236, 
8-244, 8-260, 8-362, 8-506 

I 

IBB_* values 5-405, 5-463 
icon 

destroy 8-107 
icon file format D-2 
icon size, how determined A-17 
ICONINFO A-65 
IconPos A-66 
Image 5-153 
draw 5-153 

image attribute values 5-405, 5-463 
Image Data 33-17 
IMAGEBUNDLE A-66 
Implicit Pointer 1-1 
implicit pointer data types 1-5 


In Send Message 8-201 
Inflate Rectangle 8-197 
information tables 
bit map D-1 
inheritance 9-1 
initialization file H-1 
Initialize 8-199 
Initialize DDF Area 4-15 
initialize Presentation Interface 8-199 
Input Hook 10-13 
InputHook 10-13 
Insert List Item 4-18 
Insert Listbox Item 8-203 
interchange file format G-1 
Intersect Clip Rectangle 5-155 
Intersect Rectangle 8-205 
Invalidate Rectangle 8-207 
Invalidate Region 8-209 
Invert Rectangle 8-211 
IPT A-66 
Is Child 8-213 
Is Control Enabled 8-214 
Is Menu Item Checked 8-216 
Is Menu Item Enabled 8-218 
Is Menu Item Valid 8-220 
Is Physical Input Enabled 8-222 
Is Rectangle Empty 8-223 
Is Thread Active 8-224 
Is Window 8-226 
items in a dialog template 32-21 

J 

Japanese fonts 34-23 
Journal Playback Hook 10-14 
Journal Record Hook 10-15 
JournalPlaybackHook 10-14 
JournalRecordHook 10-15 
JRN_* values 12-39 

K 

kanji 34-23 
KC_* values 12-24 
kerning A-60 

device support 2-18 
enable A-38 
number of pairs A-60 
query pairs 5-306 
kerning pair table F-8 
KERNINGPAIRS A-66 
KERNINGPAIRS data structure A-66 
Keyboard control codes 12-24 
keyboard resources 32-18 
keyboard statements 
keyboard 32-18 
KS_* values 8-176, 8-188 

L 

Label 5-157, 33-18 

generate element for 5-157 
language support dialog processing 12-83 
language support window processing 12-80 
LBB_* values 5-404, 5-462 
LCIDT * values 5-359 
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LCID_* values 5-252, 5-320, 5-337, 5-443, 5-506, 5-526 
LCOLF_* values 5-74, 5-264, 8-494 
LCOLOPT_* 5-349 

LCOLOPT_* values 5-313, 5-333, 5-343 
LCOL_* options 8-494 
LCOL_* values 5-74, 5-264 
LC_* values 5-194 
Left cursor key 8-547 
LHANDLE A-66 
Line 5-159 
draw 5-159 

query cosmetic width 5-31 1 
query end 5-308 
query geometric width 5-312 
query join 5-309 
query type 5-310 
query width 5-311 
set cosmetic width 5-498 
set end 5-491 
set geometric width 5-500 
set join 5-493 
set type 5-495 
set width 5-498 
Line at Current Position 33-18 
Lineat Given Position 33-18 
line attribute values 5-404, 5-462 
LINEBUNDLE A-66 
LINEEND_* values 5-308, 5-491 
LINEJOINj* values 5-309, 5-493 
LINETYPE_* values 5-310, 5-495 
LINEWIDTHGEOM_* values 5-312 
LINEWIDTH_* values 5-311,5-498 
list box control data 16-1 
list box control styles 16-1 
list box control window processing 16-1 
LIT_* values 16-6 
LM_DELETEALL 16-5 
LM_DELETEITEM 16-5 
LMJNSERTITEM 16-6 
LM_QUERYITEMCOUNT 16-7 
LM_QUERYITEMHANDLE 16-7 
LM_QUERYITEMTEXT 16-8 
LM_QUERYITEMTEXTLENGTH 16-9 
LM_QUERYSELECTION 16-9 
LM_QUERYTOPINDEX 16-10 
LM_SEARCHSTRING 16-11 
LM_SELECTITEM 16-12 
LM_SETITEMHANDLE 16-12 
LM_SETITEMHEIGHT 16-13 
LM_SETITEMTEXT 16-14 
LM_SETTOPINDEX 16-14 
LN_* values 16-2 
Load Accelerator Table 8-234 
Load and Process Modal Dialog 8-115 
Load Bit Map 5-161 
Load Dialog 8-236 
Load File Icon 8-239 
Load Fonts 5-163 
Load Help Table 8-241 
Load Library 8-243 
Load Menu 8-244 
Load Message 8-246 
Load Metafile 5-165 
Load Pointer 8-248 
Load Procedure 8-250 
Load Public Fonts 5-167 
Load String 8-251 


load type options 5-193 
Loader Hook 10-16 
LoaderHook 10-16 
LOADOPTION 32-2 
local identifier options 5-193 
Lock Visible Regions 8-253 
Lock Window Update 8-255 
logical color table 
create 5-74 
logical font 
delete 5-106 
LONG A-67 

LOWER_* values 5-355, 5-541 
LSS_* values 16-11 
LS_* values 16-1 
LT_* values 5-193 

M 

Make Points 8-257 
Make Rectangle 8-258 
Map Dialog Points 8-259 
Map Window Points 8-260 
Marker 5-168 

draw a series of 5-213 

draw with center at specified position 

query 5-317 

query box 5-318 

query set 5-320 

query symbol 5-317 

set 5-502 

set box 5-504 

set set 5-506 

Marker at Current Position 33-18 
Marker at Given Position 33-18 
marker attribute values 5-405, 5-463 
MARKERBUNDLE A-67 
MARKSYM_* values 5-317, 5-502 
MATRIXLF A-68 
MBB_* values 5-463 
MBID_* values 8-264 
MB_* values 8-262, 8-263 
MEMOPTION 32-2 
memory 

release 8-165 
MEMORYITEM A-68 
menu control styles 17-1 
menu control window processing 17-1 
menu item attributes 17-2 
menu item styles 17-2 
MENU statement 32-11 
MENUITEM A-68 
menus 

create 8-58 
create window 8-58 
load 8-244 
pull-down 32-14 
templates 32-15 
message 

broadcast 8-20 
dispatch 8-113 
Message Box 8-262 
Message Control Hook 10-18 
Message Filter Hook 10-20 
message processing 
introduction 11-1 
notation conventions 11-3 


5-168 


Index X-27 



message processing (continued) 
types 11-1 
message queues 1-2 
message types 11-1 
messages 

create queue 8-60 
destroy queue 8-104 
get one 8-183 
peek 8-275 
post 8-281 
post queue 8-283 
queues 1-2 
send 8-437 
wait for 8-567 
metaclass 9-1 
Metafile data format G-2 
metafile restrictions G-1 
metafiles 

create new 5-57 
delete 5-98 
general rules G-1 
load 5-165 
play 5-193 
query bits 5-321 
query length 5-323 

SAA-conforming 5-460, 5-465, 5-470, 5-472 
save 5-389 
MIA_* values 17-2 

micro-presentation space 5-391, 5-474 
mini-icon size, how determined A-17 
MINIRECORDCORE A-69 
MIS_* values 17-2, 32-15 
MIT_* values 17-9, 17-12, 17-18 
mix 

query 5-324 
set 5-510 

set background 5-415 
set foreground 5-510 
MIXED strings 34-23 
MLECTLDATA A-69 
MLEMARGSTRUCT A-70 
MLEOVERFLOW A-71 
MLE_SEARCHDATA A-71 
MLM_CHARFROMLINE 18-8 
MLM_CLEAR 18-7 
MLM_COPY 18-7 
MLM_CUT 18-8 
MLM_DELETE 18-9 
MLM_DISABLEREFRESH 18-9 
MLM_ENABLEREFRESH 18-10 
MLMEXPORT 18-11 
MLM_FORMAT 18-11 
MLMJMPORT 18-12 
MLMJNSERT 18-13 
MLM_LINEFROMCHAR 18-13 
MLM_PASTE 18-14 
MLM_QUERYBACKCOLOR 18-14 
MLM_QUERYCHANGED 18-15 
MLM_QUERYFIRSTCHAR 18-16 
MLM_QUERYFONT 18-16 
MLM_QUERYFORMATLINELENGTH 18-17 
MLM_QUERYFORMATRECT 18-18 
MLM_QUERYFORMATTEXTLENGTH 18-17 
MLM_QUERYIMPORTEXPORT 18-18 
MLM_QUERYLINECOUNT 18-19 
MLM_QUERYLINELENGTH 18-19 
MLM QUERYREADONLY 18-20 


MLM_QUERYSEL 18-20 
MLM_QUERYSELTEXT 18-21 
MLM_QUERYT ABST OP 18-22 
MLM_QUERYTEXTCOLOR 18-22 
MLM_QUERYTEXTLENGTH 18-23 
MLM_QUERYTEXTLIMIT 18-23 
MLM_QUERYUNDO 18-24 
MLM_QUERYWRAP 18-24 
MLM_RESETUNDO 18-25 
MLM_SEARCH 18-26 
M LM_SETBACKCOLOR 18-27 
MLM_SETCHANGED 18-28 
MLM_SETFIRSTCHAR 18-28 
MLM_SETFONT 18-29 
M LM_SETFORMATRECT 18-30 
MLM_SETIMPORTEXPORT 18-31 
M LMSETRE ADONLY 18-32 
MLM_SETSEL 18-31 
MLM_SETTABSTOP 18-33 
M L M_SETTEXT COLOR 18-32 
MLMSETTEXTLIMIT 18-33 
MLM_SETWRAP 18-34 
MLM_UNDO 18-35 
MLS_* values 18-2 
M M_DELETEITEM 17-8 
MM_ENDMENUMODE 17-9 
MM_INSERTITEM 17-9 
MMJSITEMVALID 17-10 
MMJTEMIDFROMPOSITION 17-11 
MMJTEMPOSITIONFROMID 17-11 
MM_QUERYITEM 17-12 
MM_QUERYITEMATTR 17-13 
MM_QUERYITEMCOUNT 17-13 
MMQUERYITEMRECT 17-14 
MM_QUERYITEMTEXT 17-15 
MMQUERYITEMTEXTLENGTH 17-15 
MM_QUERYSELITEMID 17-16 
MM_REMOVEITEM 17-17 
M M_SELECTITEM 17-18 
MM_SETITEM 17-19 
MM_SETITEMATTR 17-20 
MM_SETITEMHANDLE 17-20 
MM_SETITEMTEXT 17-21 
MM_ST ARTMENUMODE 17-22 
modal dialog 

load and process 8-115 
Modify Path 5-170,33-19 
monochrome devices 5-327 
Move 5-173 

Move to Next Character 8-268 
Move to Previous Character 8-285 
M PAR AM A-72 
MPATH_* values 5-170 
MQINFO A-72 
M RESULT A-72 
MsgCtIHook 10-18 
MsgFilterHook 10-20 
MSGF_* values 10-20 
MS_* values 12-5, 17-1 
MTI A-72 

multi-line entry field control data 18-2 
multi-line entry field control window processing 18-1 
multiple-line statements 32-7 
ACCELTABLE 32-9 
ASSOCTABLE 32-10 
DLGTEMPLATE 32-16 
MENU 32-11 
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multiple-line statements (continued) 

STRINGTABLE 32-7 
WINDOWTEMPLATE 32-16 
MWPFileSystem * A-67 
M_WPFolder * A-67 
M_WPObject * A-67 
M WPPalette * A-67 

N 

No-Opeiation 33-19 
nonstore attribute for segments 

modify (GpiSetSegmentAttrs) 5-539 
notation conventions 
messages 11-3 

notebook control window processing 
notification messages 25-3 
purpose 25-1 
styles 25-1 

window messages 25-4 
NOTIFYDELTA A-73 
NOTIFYDELTA data structure A-73 
NOTIFYRECORDEMPHASIS A-73 
NOTIFYRECORDEMPHASIS data structure A-73 
NOTIFYRECORDENTER A-74 
NOTIFYRECORDENTER data structure A-74 
NOTIFYSCROLL A-74 
NOTIFYSCROLL data structure A-74 
NULL 1-1 
NULLHANDLE 1-1 

o 

OBJCLASS A-75 
OBJ DATA A-75 
Object classes 9-2 
Offset Clip Region 5-175 
Offset Element Pointer 5-177 
Offset Rectangle 8-270 
Offset Region 5-179 
Open Clipboard 8-272 
Open Device Context 2-9 
open figure 5-20 
Open Profile 6-3 
Open Segment 5-181 
Open Window Device Context 8-273 
outline fonts 5-427, 5-430, 5-433, 5-438, 5-441, 5-445 
Outline Path 5-184, 33-19 
owner-notification messages 1 1-3 
OWNERBACKGROUND A-75 
OWNERBACKGROUND data structure A-75 
OWNERITEM A-76 
OWNERITEM data structure 12-75 
owneritem parameter 12-75, 24-6 
WM_DRAWITEM for container control 24-6 
WM_DRAWITEM for font dialog 1 2-75 

P 

PACCEL A-76 
PACCELTABLE A-76 
page viewport 
query 5-330 
set 5-516 
PAGE INFO A-76 
PAGESELECTNOTIFY A-78 


paint 

begin 8-18 
end 8-141 
Paint Region 5-186 
palette 

animate 5-8 
create 5-81 
delete 5-100 
query 5-332 
query information 5-333 
realize 8-403 
select 5-396 
set entries 5-518 
PALINFO A-78 
PANOSE A-78, F-9 
PAPSZ A-82 
PARAM A-82 
PARCPARAMS A-84 
PAREABUNDLE A-84 
parent/child/owner relationship 32-23 
Partial Arc 5-188 

Partial Arc at Current Position 33-20 
Partial Arc at Given Position 33-20 
path 

begin 5-19 

convert to region 5-191 
draw interior 5-142 
draw outline 5-184 
end 5-132 
fill 5-142 
modify 5-170 
Path to Region 5-191 
PATSYM_* values 5-335, 5-521 
pattern 

query 5-335 

pattern attribute (area) values 5-405, 5-463 
patterns 

query reference point 5-336 
query set 5-337 
set 5-521 

set reference point 5-524 
set set 5-526 
PBANDRECT A-84 
PBITMAPINFO A-84 
PBITMAPINFOHEADER A-84 
PBITMAPINFOHEADER2 A-84 
PBITMAPINF02 A-84 
PBOOKTEXT A-84 
PBOOL A-84 
PBUFFER A-84 
PBUNDLE A-84 
PBYTE A-84 
PC VKEY 1-1 
PCATCHBUF A-85 
PCDATE A-85 
PCELL A-85 
PCH A-85 
PCHAR A-85 
PCHARBUNDLE A-85 
PCLASSDET AILS A-85 
PCLASSFIELDINFO A-85 
PCLASSINFO A-85 
PCNRDRAGINFO A-85 
PCNRDRAGINIT A-85 
PCNRDRAWITEMINFO A-85 
PCNREDITDATA A-85 
PCNRINFO A-85 
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PCOLOR A-85 
PCONVCONTEXT A-85 
PCPTEXT A-85 
PCREATEPARAMS A-85 
PCREATESTRUCT A-85 
PCTIME A-85 
PCURSORINFO A-85 
PDDEINIT A-85 
PDDESTRUCT A-86 
PDELETENOTIFY A-86 
PDESKTOP A-86 
PDEVOPENDATA A-86 
PDEVOPENSTRUC A-86 
PDLGTEM PLATE A-86 
PDLGTITEM A-86 
PDRAGIMAGE A-86 
PDRAGINFO A-86 
PDRAGITEM A-86 
PDRAGTRANSFER A-86 
PDRIVDATA A-86 
PDRIVPROPS A-86 
Peek Message 8-275 
pel 

query 5-338 
set 5-528 

PENTRYFDATA A-86 
PERRINFO A-86 
PERRORID A-86 
PESCMODE A-86 
PFACENAMEDESC A-86 
PFATTRS A-86 
PFFDESCS A-87 
PFIELDINFO A-87 
PFIELDINFOINSERT A-87 
PFILEDLG A-87 
PFILEFINDBUF4 A-87 
PFIXED A-87 
PFN A-87 
PFNWP A-87 
PFOCAMETRICS type F-2 
PFONTDLG A-87 
PFONTMETRICS A-87 
PGRADIENTL A-87 
PHAB A-87 
PHBITMAP A-87 
PHCINFO A-87 
PHDC A-87 
PHELPINIT A-87 
PHELPSUBTABLE A-87 
PHELPTABLE A-87 
PHFIND A-87 
PHMF A-87 
PHMODULE A-87 
PHPAL A-87 
PHPROGARRAY A-88 
PHPROGRAM A-88 
PHPS A-88 
PHRGN A-88 
PHSEM A-88 
PHSWITCH A-88 
PHWND A-88 
PIBSTRUCT A-88 
pick aperture 

query size 5-341 
set size 5-531 
PICKAP_* values 5-531 
PICKSEL_* values 5-59, 5-63, 5-67 


PICONINFO A-89 
PICONPOS A-89 
PID A-89 
pie 

segment 5-189 
PIMAGEBUNOLE A-89 
PIPT A-89 
PIX A-89 

PKERNINGPAIRS A-89 

Place Bitmap Reference 4-5 

Place Metafile Reference 4-21 

Play Metafile 5-193 

PLINEBUNDLE A-89 

PLONG A-89 

PL_ ALTERED 12-3 

PMARGSTRUCT A-89 

PMARKERBUNDLE A-89 

PMATRIXLF A-89 

PMENUITEM A-89 

PMF_* values 5-193 

PMINIRECORDCORE A-89 

PMLE_SEARCHDATA A-89 

PMPARAM A-89 

PMQINFO A-89 

PMRESULT A-89 

PM_Q_* values A-26 

PM * flags 8-275 

PM * names H-1 

PM_* values 10-5, 10-13 

PNOTIFYDELTA A-90 

PNOTIFYRECORDEMPHASIS A-90 

PNOTIFYRECORDENTER A-90 

PNOTIFYSCROLL A-90 

POBJCLASS A-90 

POBJDATA A-90 

POBJECTS A-89 

Point Arc 5-199 

Point In Rectangle 8-289 

Point In Region 5-219 

Point Visible 5-221 

pointer 

create 8-64 
create indirect 8-66 
destroy 8-107 
draw 8-124 
hide 8-520 
implicit 1-1 
load 8-248 
query handle 8-342 
query information 8-343 
query position 8-345 
set 8-484 
set element 5-482 
set position 8-486 
show 8-520 
pointer file format D-2 
Pointer-Conversion Procedure 10-3 
POINTERINFO A-90 
pointing device 

capture messages 8-442 
POINTL A-90 
points A-90 

check whether visible 5-221 
check whether within region 5-219 
Polyfillet 5-201 
draw 5-201 
sharp 5-204 
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Polyfillet Sharp 5-204 
POLYGON A-91 
polygons 33-20 

draw a set of 5-207 
Polyline 5-209 
disjoint 5-211 
draw 5-209 
Polyline Disjoint 5-211 
Polymarker 5-213 
Polyspline 5-215 
Pop 5-217,33-21 
Pop-up Menu 8-277 
Post Device Modes 2-12 
Post Drag Message 3-24 
Post Message 8-281 
Post Queue Message 8-283 
POVERFLOW A-91 
POWNERBACKGROUND A-91 
POWNERITEM A-91 
PPAGEINFO A-91 
PPAGESELECTNOTIFY A-91 
PPALINFO A-89 
PPIBSTRUCT A-91 
PPID A-89 
PPOINTL A-91 
PPOINTS A-91 
PPOLYGON A-91 
PPRDINF03 A-91 
PPRDRIVINFO A-91 
PPRESPARAMS A-91 
PPRINTDEST A-91 
PPRINTERINFO A-91 
PPRJINF02 A-91 
PPRJINF03 A-91 
PPROGCATEGORY A-91 
PPROG DETAILS A-91 
PPROGRAMENTRY A-92 
PPROGTITLE A-92 
PPROGTYPE A-92 
PPRPORTINFO A-92 
PPRPORTINFOI A-92 
PPRQINF03 A-92 
PPRQINF06 A-92 
PPRQPROCINFO A-92 
PPSZ A-92 
PPVOID A-92 
PQMOPENDATA A-92 
PQMSG A-92 

PQUERYRECFROMRECT A-92 
PQUERYRECORDRECT A-92 
PRDINF03 A-92 
PRDRIVINFO A-93 
PRECORDCORE A-93 
PRECORDINSERT A-93 
PRECTL A-94 

predefined control statements 32-24 
predefined window classes 32-23 
PRENDERFILE A-94 
Presentation Interface 
initialize 8-199 
Presentation Manager 

query environment 8-381 
query revision level 8-381 
query version 8-381 
presentation parameters 32-22 
presentation space 
cache 8-18 


presentation space (continued) 
cached 15-11 
create 5-84 
destroy 5-108 
get a cache 8-190 
micro 5-86, 8-1 19, 8-123, 8-128, 8-190 
normal 8-119,8-123,8-128 
options 5-84, 5-533 
query 5-342 
release cache 8-420 
reset 5-382 
restore 5-384 
save 5-391 

presentation space options 5-84, 5-533 

PRESPARAMS A-94 

PrfCloseProfile 6-2 

PrfOpenProfile 6-3 

PRFPROFILE A-94 

PrfQueryProfile 6-5 

PrfQueryProfileData 6-7 

PrfQueryProfilelnt 6-10 

Prf QueryProf i leSize 6-12 

PrfQueryProfileString 6-14 

PrfReset 6-17 

PrfWriteProfileData 6-19 

PrfWriteProfileString 6-21 

PRGB2 A-94 

PRGNRECT A-94 

PRGN_* values 5-219 

primitives 

set attributes for 5-404 
PRIM_* values 5-229, 5-271, 5-404, 5-462 
PRINTDEST A-94 
PRINTERINFO A-95 
PRJINF02 A-96 
PRJINF03 A-97 
procedures 10-1 
dialog 10-2 
window 10-4 

Process Modal Dialog 8-287 
profile 

query string 6-14 
PROGCATEGORY A-99 
PROG DETAILS A-99 
PROGRAMENTRY A-100 
PROGTITLE A-100 
PROGTYPE A-100 
PROG_* values A-100 

prompted entry field control window processing 19-1 

PRPORTINFO A-101 

PRPORTINFOI A-101 

PRQINF03 A-101 

PRQINF06 A-103 

PRQPROCINFO A-105 

PSBCDATA A-105 

PSEARCHSTRING A-105 

PSF ACTORS A-105 

PSF_* values 8-169 

PSHORT A-105 

PSIZEF A-105 

PSIZEL A-105 

PSLDCDATA A-105 

PSTRL A-105 

PSTR16 A-105 

PSTR32 A-105 

PSTR64 A-105 

PSTR8 A-105 
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PSTYLECHANGE A-105 
PSWBLOCK A-106 
PSWCNTRL A-106 
PSWENTRY A-106 
PSWP A-106 
PSZ A-106 

PS_* values 5-84, 5-342, 5-533 

PTID A-106 

PTRACKINFO A-106 

PTREEITEMDESC A-106 

PUCHAR A-106 

pull-down menus 32-14 

PULONG A-106 

PUSEITEM A-106 

PUSERBUTTON A-106 

Push and Set Arc Parameters 33-23 

Push and Set Background Color 33-23 

Push and Set Background Indexed Color 33-24 

Push and Set Background Mix 33-25 

Push and Set Character Angle 33-26 

Push and Set Character Break Extra 33-26 

Push and Set Character Cell 33-27 

Push and Set Character Direction 33-28 

Push and Set Character Extra 33-28 

Push and Set Character Precision 33-29 

Push and Set Character Set 33-30 

Push and Set Character Shear 33-30 

Push and Set Color 33-31 

Push and Set Current Position 33-32 

Push and Set Extended Color 33-32 

Push and Set Fractional Line Width 33-33 

Push and Set Indexed Color 33-34 

Push and Set Individual Attribute 33-35 

Push and Set Line End 33-36 

Push and Set Line Join 33-36 

Push and Set Line Type 33-37 

Push and Set Line Width 33-38 

Push and Set Marker Cell 33-39 

Push and Set Marker Precision 33-40 

Push and Set Marker Set 33-40 

Push and Set Marker Symbol 33-41 

Push and Set Mix 33-41 

Push and Set Model Transform 33-42 

Push and Set Pattern Reference Point 33-43 

Push and Set Pattern Set 33-44 

Push and Set Pattern Symbol 33-44 

Push and Set Pick Identifier 33-45 

Push and Set Stroke Line Width 33-46 

Push and Set Text Alignment 33-47 

Push and Set Viewing Window 33-48 

PUSHORT A-106 

Put Data 5-223 

PU_* values 5-84, 5-533 

PVIOFONTCELLSIZE A-106 

PVIOSIZECOUNT A-106 

PVIS_* values 5-221 

PVOID A-106 

PVSCDATA A-106 

PVSDRAGINFO A-106 

PVSDRAGINIT A-106 

PVSTEXT A-106 

PWNDPARAMS A-106 

PWPOINT A-106 


Q 

QCD_LCT_* values 5-264 

QFC_* values 15-16 

QF_* values 5-299 

QLCT_* values 5-313 

QMOPENSTRUC A-107 

QMSG 11-1, A-108 

QS_* values 8-352 

Query Accelerator T able 8-291 

Query Active Window 8-293 

Query Anchor Block 8-294 

Query Arc Parameters 5-226 

Query Atom Length 8-295 

Query Atom Name 8-297 

Query Atom Usage 8-299 

Query Attribute Mode 5-228 

Query Attributes 5-229 

Query Background Color 5-231 

Query Background Mix 5-232 

Query Bit-Map Bits 5-233 

Query Bit-Map Dimension 5-236 

Query Bit-Map Handle 5-239 

Query Bit-Map Info Header 5-237 

Query Bit-Map Parameters 5-240 

Query Boundary Data 5-242 

Query Capture 8-302 

Query Character Angle 5-244 

Query Character Box 5-246 

Query Character Break Extra 5-248 

Query Character Direction 5-249 

Query Character Extra 5-250 

Query Character Mode 5-251 

Query Character Set 5-252 

Query Character Shear 5-253 

Query Character String Positions 5-255 

Query Character String Positions At 5-257 

Query Checkstate of Button 8-300 

Query Class Information 8-303 

Query Class Name 8-305 

Query Class Pointer-Conversion Procedure 8-307 

Query Clip Box 5-259 

Query Clip Region 5-261 

Query Clipboard Data 8-308 

Query Clipboard Format Information 8-310 

Query Clipboard Owner 8-312 

Query Clipboard Viewer 8-313 

Query Code Page 5-268, 8-314 

Query Code Page List 8-315 

Query Color 5-262 

Query Color Data 5-264 

Query Color Index 5-266 

Query Current Position 5-269 

Query Cursor Information 8-316 

Query Default Arc Parameters 5-270 

Query Default Attributes 5-271 

Query Default Graphics Character Box 5-275 

Query Default Tag 5-277 

Query Default View Matrix 5-273 

Query Default Viewing Limits 5-278 

Query Desktop Background 8-317 

Query Desktop Window 8-319 

Query Device 5-279 

Query Device Bit-Map Formats 5-280 

Query Device Capabilities 2-15 

Query Device Names 2-21 

Query Dialog Item Short 8-321 
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Query Dialog Item Text 8-323 
Query Dialog Item Text Length 8-325 
Query Draw Control 5-282 
Query Drawing Mode 5-284 
Query Edit Mode 5-285 
Query Element 5-286 
Query Element Pointer 5-288 
Query Element Type 5-290 
Query Face String 5-292 
Query Focus 8-327 
Query Font Action 5-294 
Query Font File Descriptions 5-295 
Query Font Metrics 5-297 
Query Font Width Table 5-372 
Query Fonts 5-299 

Query Full Font File Descriptions 5-301 

Query Graphics Field 5-303 

Query Hardcopy Caps 2-24 

Query Help Instance 8-328 

Query Initial Segment Attributes 5-304 

Query Kerning Pairs 5-306 

Query Line End 5-308 

Query Line Join 5-309 

Query Line Type 5-310 

Query Line Width 5-311 

Query Line Width Geom 5-312 

Query Listbox Item Text 8-331 

Query Listbox Item Text Length 8-333 

Query Logical Color Table 5-313 

Query Logical Font 5-315 

Query Marker 5-317 

Query Marker Box 5-318 

Query Marker Set 5-320 

Query Message Position 8-336 

Query Message Time 8-338 

Query Metafile Bits 5-321 

Query Metafile Length 5-323 

Query Mix 5-324 

Query Model Transform Matrix 5-325 

Query Nearest Color 5-327 

Query Number Set Identifiers 5-329 

Query Object Window 8-340 

Query Page Viewport 5-330 

Query Palette 5-332 

Query Palette Info 5-333 

Query Pattern 5-335 

Query Pattern Reference Point 5-336 

Query Pattern Set 5-337 

Query Pel 5-338 

Query Pick Aperture Position 5-340 
Query Pick Aperture Size 5-341 
Query Pointer 8-342 
Query Pointer Information 8-343 
Query Pointer Position 8-345 
Query Presentation Parameter 8-347 
Query Presentation Space 5-342 
Query Profile 6-5 
Query Profile Data 6-7 
Query Profile Integer 6-10 
Query Profile Size 6-12 
Query Profile String 6-14 
Query Queue Information 8-350 
Query Queue Status 8-352 
Query Real Colors 5-343 
Query Region Box 5-345 
Query Region Rectangles 5-347 
Query RGB Color 5-349 


Query Segment Attributes 5-351 

Query Segment Names 5-353 

Query Segment Priority 5-355 

Query Segment T ransform Matrix 5-357 

Query Session Title 8-355 

Query Set Identifiers 5-359 

Query Stop Draw 5-362 

Query Switch Entry 8-357 

Query Switch Handle 8-358 

Query Switch List 8-360 

Query System Atom Table 8-372 

Query System Color 8-362 

Query System Modal Window 8-364 

Query System Pointer 8-365 

Query System Value 8-368 

Query Tag 5-363 

Query Task Title 8-375 

Query Task Window Size and Position 8-373 

Query Text Alignment 5-364 

Query Text Box 5-365 

Query the Selected Item in Listbox 8-335 

Query Update Rectangle 8-377 

Query Update Region 8-379 

Query Version 8-381 

Query Viewing Limits 5-368 

Query Viewing Transform Matrix 5-370 

Query Window 8-382 

Query Window Device Context 8-384 

Query Window Enabled State 8-228 

Query Window Handle From Device Context 8-572 

Query Window Handle From Identifier 8-574 

Query Window Long 8-398 

Query Window Model 8-385 

Query Window Pointer 8-390 

Query Window Pointer-Conversion Procedure 8-397 

Query Window Position 8-386 

Query Window Process 8-388 

Query Window Rectangle 8-392 

Query Window Short 8-400 

Query Window Showing 8-230 

Query Window Text 8-394 

Query Window T ext Length 8-396 

Query Window Visibility 8-232 

Query Workplace Object Handle 8-402 

QUERYRECFROMRECT A-108 

QUERYRECFROM RECT data structure A-108 

QUERYRECORDRECT A-109 

QUERYRECORDRECT data structure A-109 

queue 

query information 8-350 

query status 8-352 
QV_* values 8-381 
QWL_USER in containers 24-1 
QWL_* values 8-398 
QWS_* values 8-400 
QW_*values 8-382 

R 

radio button 13-1 

raster fonts 5-427, 5-430, 5-433, 5-438, 5-441 , 5-445 

Realize Palette 8-403 

RECORDCORE A-110 

RECORDINSERT A-111 

RECORDINSERT data structure A-111 

RECORDITEM A-111 

rectangle 
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rectangle (continued) 
calculate frame 8-22 
check whether visible 5-376 
check whether within region 5-374 
compare for equality 8-148 
convert to graphic 8-258 
copy 8-39 
draw border 8-121 
draw interior 8-121 
exclude from clipping region 5-140 
fill 8-154 
inflate 8-197 
intersect 8-205 
intersect clip 5-155 
invalidate 8-207 
invert 8-211 

query if point within 8-289 
query update 8-377 
set coordinates 8-489 
set empty 8-491 
subtract 8-538 
validate 8-560 
Rectangle In Region 5-374 
Rectangle Visible 5-376 
RECTDIR_* values A-114 
RECTL A-112 
region 

query box 5-345 
query rectangles 5-347 
regions 

check if identical 5-134 

check whether point within 5-219 

check whether rectangle within 5-374 

combine 5-49 

create 5-88 

destroy 5-110 

frame 5-146 

invalidate 8-209 

move 5-179 

offset 5-179 

paint 5-186 

set 5-536 

validate 8-562 

Register User Data Type 8-408 

Register User Message 8-415 

Register User Message Hook 10-21 

Register Window Class 8-405 

Register Workplace Object Class 8-407 

RegisterUserMsg 10-21 

Relative Line at Current Position 33-22 

Relative Line at Given Position 33-22 

Release Hook 8-418 

Release Presentation Space 3-44, 8-420 

Remove Dynamics 5-378 

Remove Presentation Parameter 8-422 

Remove Switch Entry 8-424 

RENDERFILE A-112 

Replace Workplace Object Class 8-426 

Request Mutex Semaphore 8-427 

reserved messages 12-1 

Reset Boundary Data 5-381 

reset options 5-194 

Reset Presentation Manager 6-17 

Reset Presentation Space 5-382 

resource 

load string from 8-251 
resource definitions 32-2 


resource file specification 32-27 
resource files 
definitions 32-2 
introduction 32-1 
source file specification 32-27 
syntax definitions 32-1 
resource script file 
specification 32-2 
resource script file specification 
keyboard resources 32-18 
user-defined resources 32-3 
resource statements 
ACCELTABLE 32-9 
ASSOCTABLE 32-10 
dialog template 32-16 
directives 32-4 
DLGTEM PLATE 32-16 
MENU item definition 32-13 
MENU statement 32-11 
multiple-line 32-7 
single line 32-2 
STRINGTABLE 32-7 
user-defined 32-3 
window template 32-16 
WINDOWTEMPLATE 32-16 
Restore Presentation Space 5-384 
Restore Window Position 8-429 
RES_* values 5-194 
RGB 5-77, A-113 

RGB (red-green-blue) 5-264, 5-343, 5-453, 8-362 
query color 5-349 
RGB2 A-113 
RGNRECT A-114 

RGN_* values 5-140, 5-155, 5-345, 5-451 , 8-379 

Right cursor key 8-547 

Roman text 5-435 

ROP_* values 5-24, 5-112, 5-567 

Rotate Transform 5-386 

RRGN_* values 5-374 

RT_* values 32-27 

RUM_* values 8-415 

RV!S_* values 5-376 

s 

SAA-conforming metafiles 5-475 

Save Metafile 5-389 

Save Presentation Space 5-391 

Save Window Position 8-430 

SBCDATA A-114 

SBCS 34-23 

SBMP_* values 8-194 

SBMQUERYPOS 20-4 

SBMQUERYRANGE 20-4 

SBMSETPOS 20-5 

SBMSETSCROLLBAR 20-6 

SBMSETTHUMBSIZE 20-7 

SBS_* values 20-1 

SB_* values 12-38, 12-68, 28-2, 28-5 

Scale Matrix 5-393 

SCP_* values 5-448 

scroll bar control data 20-1 

scroll bar control window.processing 20-1 

scroll bar styles 20-1 

Scroll Window 8-432 

SC_* values 15-21 

SDW_* values 5-362, 5-546 
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SEARCHSTRING A-115 
SEARCHSTRING data structure A-115 
SEGEM_* values 5-285, 5-480 
segment attributes 
chained 5-539 
detectability 5-539 
highlight 5-539 
nonstore 5-539 
store 5-539 
transformability 5-539 
visibility 5-539 

Segment Characteristics 33-22 
segments 

add comment 5-51 
call matrix 5-31 
close current 5-47 
correlate 5-67 
correlate chain 5-59 
correlate section of chain 5-63 
delete all 5-104 
delete retained 5-102 
draw 5-123 
draw chain 5-117 
draw section of chain 5-121 
get graphic data from 5-150 
open 5-181 
query attributes 5-351 
query initial attributes 5-304 
query names 5-353 
query priority 5-355 
query transform matrix 5-357 
return last error during drawing 5-138 
set attributes 5-538 
set initial attributes 5-488 
set priority 5-541 
set transform matrix 5-543 
Select Palette 5-396 
Send Drag Message 3-45 
Send Message 8-437 
Send Message Hook 10-23 
Send Message to Dialog Item 8-435 
SendMsgHook 10-23 
SEPARATOR menu item 32-15 
session title 
query 8-355 

Set Accelerator Table 8-439 

Set Active Window 8-441 

Set Arc Parameters 5-398, 33-23 

Set Attribute Mode 5-401 

Set Attributes 5-404 

Set Background Color 5-412, 33-23 

Set Background Indexed Color 33-24 

Set Background Mix 5-415, 33-25 

Set Bit Map 5-418 

Set Bit-Map Bits 5-420 

Set Bit-Map Dimension 5-423 

Set Bit-Map Identifier 5-425 

Set Capture 8-442 

Set Character Angle 5-427, 33-26 

Set Character Box 5-430 

Set Character Break Extra 5-433, 33-26 

Set Character Cell 33-27 

Set Character Direction 5-435, 33-28 

Set Character Extra 5-438, 33-28 

Set Character Mode 5-440 

Set Character Precision 33-29 

Set Character Set 5-443, 33-30 


Set Character Shear 5-445, 33-30 
Set Checkstate of Button 8-30 
Set Class Message Interest 8-444 
Set Class Pointer-Conversion Procedure 8-447 
Set Clip Path 5-448, 33-31 
Set Clip Region 5-451 
Set Clipboard Data 8-449 
Set Clipboard Owner 8-452 
Set Clipboard Viewer 8-454 
Set Code Page 5-456, 8-456 
Set Color 5-453, 33-31 
Set Color of Text 4-26 
Set Current Position 5-458, 33-32 
Set Default Arc Parameters 5-460 
Set Default Attributes 5-462 
Set Default T ag 5-470 
Set Default View Matrix 5-467 
Set Default Viewing Limits 5-472 
Set Desktop Background 8-457 
Set Dialog Item Short 8-459 
Set Dialog Item Text 8-461 
Set Drag Image 3-48 
Set Draw Control 5-474 
Set Drawing Mode 5-477 
Set Edit Mode 5-480 
Set Element Pointer 5-482 
Set Element Pointer At Label 5-484 
Set Extended Color 33-32 
Set File Icon 8-463 
Set Focus 8-464 
Set Fractional Line Width 33-33 
Set Graphics Field 5-486 
Set Hook 8-466 
set identifier 
delete 5-106 
Set Indexed Color 33-34 
Set Individual Attribute 33-35 
Set Initial Segment Attributes 5-488 
Set Keyboard State Table 8-468 
Set Line End 5-491, 33-36 
Set Line Join 5-493, 33-36 
Set Line Type 5-495, 33-37 
Set Line Width 5-498, 33-38 
Set Line Width Geom 5-500 
Set Listbox Item Text 8-470 
Set Marker 5-502 
Set Marker Box 5-504 
Set Marker Cell 33-39 
Set Marker Precision 33-40 
Set Marker Set 5-506, 33-40 
Set Marker Symbol 33-41 
Set Menu Item Text 8-472 
Set Message Interest 8-473 
Set Message Mode 8-476 
Set Metafile Bits 5-508 
Set Mix 5-510, 33-41 
Set Model Transform 33-42 
Set Model Transform Matrix 5-513 
Set Multiple Window Positions 8-478 
Set Object Data 8-480 
Set Owner 8-481 
Set Page Viewport 5-516 
Set Palette Entries 5-518 
Set Parent 8-482 
Set Pattern 5-521 

Set Pattern Reference Point 5-524, 33-43 
Set Pattern Set 5-526, 33-44 



Set Pattern Symbol 33-44 

Set Pel 5-528 

Set Pick Identifier 33-45 

Set Pick-Aperture Position 5-530 

Set Pick-Aperture Size 5-531 

Set Pointer 8-484 

Set Pointer Position 8-486 

Set Pointing Device Pointer 3-53 

Set Presentation Parameter 8-487 

Set Presentation Space 5-533 

Set Rectangle 8-489 

Set Rectangle Empty 8-491 

Set Region 5-536 

Set Segment Attributes 5-538 

Set Segment Boundary 33-45 

Set Segment Priority 5-541 

Set Segment Transform Matrix 5-543 

Set Stop Draw 5-546 

Set Stroke Line Width 33-46 

Set Synchronization Mode 8-492 

Set System Colors 8-494 

Set System Modal Window 8-500 

Set System Value 8-502 

Set Tag 5-548 

Set Text Alignment 5-550,33-47 

Set Values in DRAGITEM 3-50 

Set Viewing Limits 5-553 

Set Viewing Transform 33-48 

Set Viewing Transform Matrix 5-555 

Set Viewing Window 33-48 

Set Window Enabled State 8-135 

Set Window Pointer-Conversion Procedure 8-514 

Set Window Position 8-506 

Set Window Text 8-512 

Set Window Word Bits 8-504 

Set Window Word Long 8-515 

Set Window Word Short 8-517 

Set Window Words Pointer 8-510 

SF ACTORS A-115 

SHANDLE A-116 

Sharp Fillet at Current Position 33-50 
Sharp Fillet at Given Position 33-50 
SHE_* values A-101 
SHORT A-116 
Show Cursor 8-518 
Show Pointer 8-520 
Show Tracking Rectangle 8-522 
Show Window 8-523 
Shutdown System 8-525 
single-byte character set 1-6 
single-byte character sets 34-23 
SIZEF A-116 
SIZEL A-116 
SLDCDATA A-116 
SLDCDAT A data structure A-1 1 6 
slider control window processing 
data structures 26-3 
notification messages 26-4 
purpose 26-1 
styles 26-1 

window messages 26-7 
SLM_ADDDETENT 26-7 
SLMQUERYDETENTPOS 26-7 
SLMQUERYSCALETEXT 26-8 
SLM_QUERYSLIDERINFO 26-9 
SLMQUERYTICKPOS 26-11 
SLMQUERYTICKSIZE 26-11 


SLM_REMOVEDETENT 26-12 
SLM_SETSCALETEXT 26-13 
SLM_SETSLIDERINFO 26-13 
SLMSETTICKSIZE 26-15 
SLS_* values 26-1 
SMHSTRUCT A-1 17 
SMIM_* values 8-444, 8-473 
SMI_* values 8-444, 8-473 
SMQUERYHANDLE 22-3 
SM_SETHANDLE 22-4 
Sound Alarm 8-11 
source resource file 32-27 
SPBM_OVERRIDESETLIMITS 21-3 
SPBM_QUERYLI MITS 21-4 
SPBM_QUERYVALUE 21-4 
SPBM_SET ARRAY 21-6 
SPBM_SETCURRENTVALUE 21-6 
SPBM_SETLIMITS 21-7 
SPBMSETMASTER 21-8 
SPBMSETTEXTLI MIT 21-9 
SPBM_SPINDOWN 21-9 
SPBM_SPINUP 21-10 
Specify Text Font 4-29 
Specify Text Font Style 4-32 
spin button control window processing 21-1 
notification message 21-2 
purpose 21-1 
styles 21-1 
SpIControlDevice 7-2 
SpICopyJob 7-5 
SpICreateDevice 7-7 
SpICreateQueue 7-10 
SpIDeleteDevice 7-14 
SpIDeleteJob 7-16 
SpIDeleteQueue 7-18 
SplEnumDevice 7-20 
SplEnumDriver 7-23 
SplEnumJob 7-26 
SplEnumPort 7-29 
SplEnumPrinter 7-32 
SplEnumQueue 7-35 
SplEnumQueueProcessor 7-39 
SPLERR A-1 17 
SplHoidJob 7-42 
SplHoldQueue 7-44 
SpIPurgeQueue 7-46 
SpIQmAbort 7-48 
SpIQmAbortDoc 7-49 
SpIQmClose 7-50 
SpIQmEndDoc 7-51 
SpIQmOpen 7-53 
SpIQmStartDoc 7-55 
SpIQmWrite 7-57 
SpIQueryDevice 7-59 
SpIQueryJob 7-62 
SpIQueryQueue 7-66 
SpIReleaseJob 7-70 
SpIReleaseQueue 7-72 
SpISetDevice 7-74 
SpISetJob 7-77 
SpISetQueue 7-81 
SPL_* values 7-51,7-53 
Spool File Close 7-50 
spooler 

control device 7-2 
copy job 7-5 
create device 7-7 
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spooler (continued) 
create queue 7-10 
delete device 7-14 
delete job 7-16 
delete queue 7-18 
enumerate device 7-20 
enumerate driver 7-23, 7-29 
enumerate job 7-26 
enumerate printer 7-32 
enumerate queue 7-35 
enumerate queue processor 7-39 
hold job 7-42 
hold queue 7-44 
purge queue 7-46 
query device 7-59 
query job 7-62 
query queue 7-66 
queue manager abort 7-48 
queue manager abort document 7-49 
queue manager close 7-50 
queue manager end document 7-51 
queue manager open 7-53 
queue manager start document 7-55 
queue manager write 7-57 
release job 7-70 
release queue 7-72 
set device 7-74 
set job Information 7-77 
set queue 7-81 
Spooler Control Device 7-2 
Spooler Copy Job 7-5 
Spooler Create Device 7-7 
Spooler Create Queue 7-10 
Spooler Delete Device 7-14 
Spooler Delete Job 7-16 
Spooler Delete Queue 7-18 
Spooler Enumerate Device 7-20 
Spooler Enumerate Driver 7-23 
Spooler Enumerate Job 7-26 
Spooler Enumerate Port 7-29 
Spooler Enumerate Print Destinations 7-32 
Spooler Enumerate Queue 7-35 
Spooler Enumerate Queue Processor 7-39 
Spooler File Abort 7-48 
Spooler File Abort Document 7-49 
Spooler File End Document 7-51 
Spooler File Open 7-53 
Spooler File Start Document 7-55 
Spooler File Write 7-57 
Spooler Hold Job 7-42 
Spooler Hold Queue 7-44 
Spooler Purge Queue 7-46 
Spooler Query Device 7-59 
Spooler Query Job 7-62 
Spooler Query Queue 7-66 
Spooler Release Job 7-70 
Spooler Release Queue 7-72 
Spooler Set Device 7-74 
Spooler Set Job 7-77 
Spooler Set Queue 7-81 
SPTR_* values 8-365 
SS_* values 22-1 
standard bit-map formats D-1 
Standard File Dialog 8-152 
Standard File Dialog Default Procedure 8-87 
Standard Font Dialog 8-163 
Standard Font Dialog Default Procedure 8-88 


Start Timer 8-529 

static control data 22-2 

static control styles 22-1 

static control window processing 22-1 

Stop Timer 8-531 

storage mapping of data types 1-6 

store attribute for segments 

modify (GpiSetSegmentAttrs) 5-539 
Store Window Position 8-533 
string 

convert to uppercase 8-556 
string handle 
create 3-5 
delete 3-10,3-11 
strings 

load from resource 8-251 
substitute 8-536 
STRINGTABLE statement 32-7 
Stroke Path 5-558 
STRUCT A-117 
structures A-1 
STR16 A-117 
STR32 A-117 
STR64 A-117 
STR8 A-117 
STYLECHANGE A-117 
Subclass Window 8-534 
submenus 32-14 
Substitute Strings 8-536 
Subtract Rectangle 8-538 
suppression options 5-194 
SUP_* values 5-194 
SV_* values 

effect on container icon size A-17 
effect on container mini-icon size A-17 
SWBLOCK A-1 18 
SWCNTRL A-1 18 
SWENTRY A-1 19 
Switch To Program 8-540 
SWL_* values A-1 19 
SWP A-1 19 

SWP_* values 8-386, 8-506, 12-69, A-120 
SW_* options 8-432 
SYSCLR_* indexes 8-494 
SYSINFj* values 8-381 
system color 
query 8-362 
set 8-494 
system pointer 
query 8-365 
system value 
query 8-368 
set 8-502 


T 

tag 

query 5-363 
query default 5-277 
set 5-548 

TA_* values 5-550,5-551 
TBM_QUERYHILITE 23-3 
TBM_SETHILITE 23-3 
templates 

dialog 32-19 
format 32-15 
menus 32-15 


Index 
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Terminate 8-542 
Terminate Application 8-544 
text 

draw 8-126 
query alignment 5-364 
query box 5-365 
set alignment 5-550 
TF_* values A-121 
ThunkProc 10-3 
TID A-120 
timer 

start 8-529 
title bar 

control data 23-1 
control window processing 23-1 
style 23-1 
TRACKINFO A-120 
tracking rectangle 
hide 8-522 
show 8-522 
transform matrix 

query model 5-325 
rotate 5-386 
scale 5-393 
set model 5-513 
translate 5-560 

transformability attribute for segments 
modify (GpiSetSegmentAttrs) 5-539 
transforms 

set viewing 5-555 

TRANSFORM-* values 5-31 , 5-386, 5-393, 5-467, 5-513, 
5-543, 5-555, 5-560 
Translate Accelerator 8-550 
Translate Character with Code Page 8-40 
Translate Matrix 5-560 
Translate String with Code Page 8-42 
TREEITEMDESC A-122 
triplets G-2 
TXTBOX* values 5-366 

u 

UCHAR A-122 
ULONG A-122 
Union Rectangle 8-552 
Unload Fonts 5-563 
Unload Public Fonts 5-565 
Up cursor key 8-547 
update region 
exclude 8-150 
query 8-379 
Update Window 8-554 
Uppercase Character 8-558 
Uppercase String 8-556 
USEITEM A-122 
user-defined resources 32-3 
USERBUTTON A-122 
USHORT A-123 


V 

Validate Rectangle 8-560 
Validate Region 8-562 
value set control window processing 
data structures 27-4 
notification messages 27-5 
purpose 27-1 


value set control window processing (continued) 
styles 27-1 

window messages 27-8 

Verify Given Rendering Mechanism and Format 3-57 

Verify Native Rendering Mechanism and Format 3-55 

Verify True Type of Dragged Object 3-59 

Verify Type of Dragged Object 3-61 

Verify Types 3-63 

VGA 2-19 

VIA_* values 

querying item attributes 27-9 
setting item attributes 27-15 
view matrix 

query default 5-273 
viewing limits 
query 5-368 
query default 5-278 
set 5-553 
viewing transform 
set default 5-467 
viewing transforms 
query 5-370 
VIEWITEM A-123 
viewports 

query page 5-330 
VIOFONTCELLSIZE A-123 
VIOSIZECOUNT A-123 
virtual key definitions 1-1 
visibility attribute for segments 

modify (GpiSetSegmentAttrs) 5-539 
VK_* values 8-176, A-1 
VM_QUERYITEM 27-8 
VM_QUERYITEMATTR 27-9 
VM_QUERYMETRICS 27-11 
VM_QUERYSELECTEDITEM 27-12 
VM_SELECTITEM 27-12 
VM_SETITEM 27-13 
VM_SETITEMATTR 27-14 
VM_SETMETRICS 27-16 
VOID A-123 
VSCDATA A-123 
VSCDATA data structure A-123 
VSDRAGINFO A-123 
VSDRAGINFO data structure A-123 
VSDRAGINIT A-124 
VSTEXT A-124 
VS_* values 27-1 

w 

Wait Event Semaphore 8-565 
Wait Message 8-567 

Wait MuxWait Semaphore or Message 8-569 

WA_* values 8-1 1 

WCS_* values 8-35 

WC_* classes 8-398 

WCj* values 11-2,23-1 

WinAddAtom 8-7 

WinAddSwitchEntry 8-9 

Win Alarm 8-11 

WinAssociateHelpInstance 8-13 
WinBeginEnumWindows 8-16 
WinBeginPaint 8-18 
WinBroadcastMsg 8-20 
WinCalcFrameRect 8-22 
WinCallMsgFilter 8-24 
WinCancelShutdown 8-26 
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WinChangeSwitchEntry 8-28 
WinCheckButton 8-30 
WinCheckMenultem 8-32 
WinCloseClipbrd 8-34 
WinCompareStrings 8-35 
WinCopyAccelTable 8-37 
WinCopyRect 8-39 
WinCpTranslateChar 8-40 
WinCpTranslateString 8-42 
WinCreateAccelTable 8-44 
WinCreateAtomTable 8-46 
WinCrealeCursor 8-48 
WinCreateDIg 8-50 
WinCreateFrameControls 8-52 
WinCreateHelpInstance 8-54 
WinCreateHelpTable 8-56 
WinCreateMenu 8-58 
WinCreateMsgQueue 8-60 
WinCreateObject 8-62 
WinCreatePointer 8-64 
WinCreatePointerlndirect 8-66 
WinCreateStdWindow 8-68 
WinCreateSwitchEntry 8-72 
WinCreateWindow 8-74 
WinOdelnitiate 8-78 
WinDdePostMsg 8-80 
WinOdeRespond 8-83 
WinDefDIgProc 8-85 
WinDefFileDIgProc 8-87 
WinDefFontDIgProc 8-88 
WinDefWindowProc 8-89 
WinDeleteAtom 8-91 
WinDeleteLboxItem 8-93 
WinDeleteLibrary 8-95 
WinDeleleProcedure 8-96 
WinDeregisterObjectClass 8-97 
WinDestroyAccelTable 8-98 
WinDeslroyAtomTable 8-99 
WinDestroyCursor 8-101 
WinDestroyHelpInstance 8-102 
WinOestroyMsgQueue 8-104 
WinDestroyObject 8-106 
WinDestroyPoinler 8-107 
WinDestroyWindow 8-109 
WinDismissOlg 8-111 
WinDispatchMsg 8-113 
WinDIgBox 8-115 
window 

create 8-74 

destroy 8-109 

query 8-382 

query active 8-293 

query class name 8-305 

query desktop 8-319 

query device context for 8-384 

query handle from device context 8-572 

query pointer 8-390 

query position 8-386 

query size 8-386 

query text 8-394 

query text length 8-396 

query unsigned long integer value of 8-398 

query unsigned short integer value of 8-400 

register class of 8-405 

scroll 8-432 

set message interest 8-473 
set multiple positions 8-478 


window (continued) 
set owner 8-481 
set position 8-506 
set to system modal 8-500 
update 8-554 
window class 

set message interest 8-444 
window class styles 12-1 
Window From Point 8-576 
window list 

remove entry 8-424 
Window List title 
query 8-375 
Window Procedure 10-4 
window processing 
button control 13-1 
combo box control 19-1 
container control 24-1 
control 11-2 
default 11-1, 12-1 
entry field control 14-1 
frame control 15-1 
language support 12-80 
list box control 16-1 
menu control 17-1 
multi-line entry field control 18-1 
notebook control 25-1 
prompted entry field control 19-1 
scroll bar control 20-1 
slider control 26-1 
spin button control 21-1 
static control 22-1 
value set control 27-1 
Window Start Application 8-526 
windows 

create standard 8-68 

create standard frame controls 8-52 

define procedure 10-4 

enable update 8-137 

find descendant 8-576 

get maximum position 8-179 

get minimum position 8-181 

get multiples from identities 8-266 

invoke default procedure 8-89 

is handle valid 8-226 

map points 8-260 

open device context 8-273 

process message box 8-262 

query class information 8-303 

query descendancy 8-213 

query enabled state 8-228 

query handle from identifier 8-574 

query is child 8-213 

query object 8-340 

query rectangle 8-392 

query system modal 8-364 

query visibility 8-232 

set active 8-441 

set enabled state 8-135 

set parent 8-482 

set text 8-512 

set visibility state 8-137, 8-523 
show 8-523 
start flashing 8-158 
stop flashing 8-158 
WINDOWTEMPLATE statement 32-16 
WinDrawBitmap 8-118 
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WinDrawBorder 8-121 
WinDrawPointer 8-124 
WinDrawText 8-126 
WinEmptyClipbrd 8-130 
WinEnableControl 8-131 
WinEnableMenultem 8-132 
WinEnablePhysInput 8-134 
WinEnableWindow 8-135 
WinEnableWindowUpdate 8-137 
WinEndEnumWindows 8-139 
WinEndPaint 8-141 
WinEnumClipbrdFmls 8-143 
WinEnumDIgltem 8-145 
WinEnumObjectClasses 8-147 
WinEqualRect 8-148 
WinExcludeUpdateRegion 8-150 
WinFileDIg 8-152 
WinFillRect 8-154 
WinFindAtom 8-156 
WinFlashWindow 8-158 
WinFocusChange 8-160 
WinFontDIg 8-163 
WinFreeErrorlnfo 8-165 
WinFreeFileDIgList 8-166 
WinFreeFilelcon 8-168 
WinGetClipPS 8-169 
WinGetCurrentTime 8-171 
WinGelDIgMsg 8-172 
WinGelErrorlnfo 8-175 
WinGelKeySlate 8-176 
WinGetLastError 8-178 
WinGetMaxPosition 8-179 
WinGetMinPosition 8-181 
WinGetMsg 8-183 
WinGelNextWindow 8-186 
WinGetPhysKeyState 8-188 
WinGetPS 8-190 
WinGetScreenPS 8-192 
WinGetSysBitmap 8-194 
WinlnflateRect 8-197 
Winlnitialize 8-199 
WinlnSendMsg 8-201 
WinlnsertLboxItem 8-203 
WinlntersectRect 8-205 
WinlnvalidateRect 8-207 
WinlnvalidateRegion 8-209 
WinlnvertRect 8-211 
WinlsChild 8-213 
WinlsControlEnabled 8-214 
WinlsMenultemChecked 8-216 
WinlsMenultemEnabled 8-218 
WinlsMenultemValid 8-220 
WinlsPhysInputEnabled 8-222 
WinlsRectEmpty 8-223 
WinlsThreadActive 8-224 
WinlsWindow 8-226 
WinlsWindowEnabled 8-228 
WinlsWindowShowing 8-230 
WinlsWindowVisible 8-232 
WinLoadAccelTable 8-234 
WinLoadDIg 8-236 
WinLoadFilelcon 8-239 
WinLoadHelpTable 8-241 
WinLoadLibrary 8-243 
WinLoadMenu 8-244 
WinLoadMessage 8-246 
WinLoadPointer 8-248 


WinLoadProcedure 8-250 
WinLoadString 8-251 
WinLockVisRegions 8-253 
WinLockWindowUpdate 8-255 
WinMakePoints 8-257 
WinMakeRect 8-258 
WinMapDIgPoints 8-259 
WinMapWindowPoints 8-260 
WinMessageBox 8-262 
WinMultWindowFromIDs 8-266 
WinNextChar 8-268 
WinOffsetRect 8-270 
WinOpenClipbrd 8-272 
WinOpenWindowDC 8-273 
WinPeekMsg 8-275 
WinPopupMenu 8-277 
WinPostMsg 8-281 
WinPostQueueMsg 8-283 
WinPrevChar 8-285 
WinProcessDIg 8-287 
WinRInRect 8-289 
WinQueryAccelTable 8-291 
WinQueryActiveWindow 8-293 
WinQueryAnchorBlock 8-294 
WinQueryAtomLength 8-295 
WinQueryAtomName 8-297 
WinQueryAtomllsage 8-299 
WinQueryButtonCheckstate 8-300 
WinQueryCapture 8-302 
WinQueryClassInfo 8-303 
WinQueryClassName 8-305 
WinQueryClassThunkProc 8-307 
WinQueryClipbrdData 8-308 
WinQueryClipbrdFmtlnfo 8-310 
WinQueryClipbrdOwner 8-312 
WinQueryClipbrdViewer 8-313 
WinQueryCp 8-314 
WinQueryCpList 8-315 
WinQueryCursorlnfo 8-316 
WinQueryDesktopBkgnd 8-317 
WinQueryDesktopWindow 8-319 
WinQueryDIgltemShort 8-321 
WinQueryDIgllemText 8-323 
WinQueryDIgltemTextLength 8-325 
WinQueryFocus 8-327 
WinQueryHelpInstance 8-328 
WinQueryLboxCount 8-330 
WinQueryLboxItemText 8-331 
WinQueryLboxItemTextLength 8-333 
WinQueryLboxSelectedltem 8-335 
WinQueryMsgPos 8-336 
WinQueryMsgTime 8-338 
WinQueryObject 8-402 
WinQueryObjectWindow 8-340 
WinQueryPointer 8-342 
WinQueryPointerlnfo 8-343 
WinQueryPointerPos 8-345 
WinQueryPresParam 8-347 
WinQueryQueuelnfo 8-350 
WinQueryQueueStatus 8-352 
WinQuerySessionTitle 8-355 
WinQuerySwitchEntry 8-357 
WinQuerySwitchHandle 8-358 
WinQuerySwitchList 8-360 
WinQuerySysColor 8-362 
WinQuerySysModalWindow 8-364 
WinQuerySysPointer 8-365 
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WinQuerySystemAtomTable 8-372 
WinQuerySysValue 8-368 
WinQueryTaskSizePos 8-373 
WinQueryTaskTitle 8-375 
WinQueryUpdateRect 8-377 
WinQueryUpdateRegion 8-379 
WinQueryVersion 8-381 
WinQueryWindow 8-382 
WinQueryWindowDC 8-384 
WinQueryWindowModel 8-385 
WinQueryWindowPos 8-386 
WinQueryWindowProcess 8-388 
WinQueryWindowPtr 8-390 
WinQueryWindowRect 8-392 
WinQueryWindowText 8-394 
WinQueryWindowTextLength 8-396 
WinQueryWindowThunkProc 8-397 
WinQueryWindowULong 8-398 
WinQueryWindowUShort 8-400 
WinRealizePalette 8-403 
WinRegisterClass 8-405 
WinRegisterObjectClass 8-407 
WinRegisterUserDatatype 8-408 
WinRegisterllserMsg 8-415 
WinReleaseHook 8-418 
WinReleasePS 8-420 
WinRemovePresParam 8-422 
WinRemoveSwitchEntry 8-424 
WinReplaceObjectClass 8-426 
WinRequestMutexSem 8-427 
WinRestoreWindowPos 8-429 
WinSaveWindowPos 8-430 
WinScrollWindow 8-432 
WinSendDIgltemMsg 8-435 
WinSendMsg 8-437 
WinSetAccelTable 8-439 
WinSetActiveWindow 8-441 
WinSetCapture 8-442 
WinSetClassMsglnterest 8-444 
WinSetClassThunkProc 8-447 
WinSetClipbrdOata 8-449 
WinSetClipbrdOwner 8-452 
WinSetClipbrdViewer 8-454 
WinSetCp 8-456 
WinSetDesktopBkgnd 8-457 
WinSetDIgltemShort 8-459 
WinSetDIgltemText 8-461 
WinSetFilelcon 8-463 
WinSetFocus 8-464 
WinSetHook 8-466 
WinSetKeyboardStateTable 8-468 
WinSetLboxItemText 8-470 
WinSetMenultemText 8-472 
WinSetMsglnterest 8-473 
WinSetMsgMode 8-476 
WinSetMultWindowPos 8-478 
WinSetObjectData 8-480 
WinSetOwner 8-481 
WinSelParent 8-482 
WinSetPointer 8-484 
WinSetPointerPos 8-486 
WinSetPresParam 8-487 
WinSetRect 8-489 
WinSelRectEmpty 8-491 
WinSetSynchroMode 8-492 
WinSetSysColors 8-494 
WinSetSysModalWindow 8-500 


WinSetSysValue 8-502 

WinSetWindowBits 8-504 

WinSetWindowPos 8-506 

WinSetWindowPtr 8-510 

WinSetWindowText 8-512 

WinSetWindowThunkProc 8-514 

WinSetWindowULong 8-515 

WinSetWindowUShort 8-517 

WinShowCursor 8-518 

WinShowPointer 8-520 

WinShowTrackRect 8-522 

WinShowWindow 8-523 

WinShutdownSystem 8-525 

WinStartApp 8-526 

WinStartTimer 8-529 

WinStopTimer 8-531 

WinSloreWindowPos 8-533 

WinSubclassWindow 8-534 

WinSubstituteStrings 8-536 

WinSublraclRect 8-538 

WinSwitchToProgram 8-540 

WinTerminate 8-542 

WinTerminaleApp 8-544 

WinTrackRect 8-546 

WinTranslateAccel 8-550 

WinUnionRect 8-552 

WinUpdateWindow 8-554 

WinUpper 8-556 

WinUpperChar 8-558 

WinValidateRect 8-560 

WinValidateRegion 8-562 

WinWaitEventSem 8-565 

WinWaitMsg 8-567 

WinWailMuxWaitSem 8-569 

WinWindowFromDC 8-572 

WinWindowFromID 8-574 

WinWindowFromPoint 8-576 

WM_ ACTIVATE 8-109, 8-508, 12-3 

WM_ ACTIVATE (in Frame Controls) 15-6 

WM_ACTIVATE (Language Support Dialog) 12-83 

WM_ACTIVATE (Language Support Window) 12-80 

WM_ADJUSTFRAMEPOS 15-6 

WM_ AD JUSTWI N DO WPOS 8-508, 12-5 

WMAPPTERMINATENOTIFY 12-4 

WM_BEGINDRAG 12-6 

WM_BEGINSELECT 12-7 

WM_BUTTON1 CLICK 12-7 

WM_BUTTON1 DBLCLK 12-10 

WM_BUTTON1 DBLCLK (in Frame Controls) 15-7 

WM_BUTTON1 DBLCLK (in Multiline Entry Fields) 18-36 

WMBUTTON1 DOWN 12-13 

WMBUTTON1 DOWN (in Frame Controls) 15-8 

WMBUTTON1 DOWN (in Multiline Entry Fields) 18-36 

WM_BUTTON1 MOTIONEND 12-14 

WM_BUTTON 1 MOTIONST ART 12-14 

WM_BUTTON1UP 12-19 

WM_BUTTON1UP (in Frame Controls) 15-8 

WM_BUTTON1UP (in Multiline Entry Fields) 18-37 

WM_BUTTON2CLICK 12-8 

WM_BUTTON2DBLCLK 12-11 

WM_BUTTON2DBLCLK (in Frame Controls) 15-7 

WM_BUTTON2DOWN 12-15 

WM_BUTTON2DOWN (in Frame Controls) 15-8 

WM_BUTTON2MOTIONEND 12-16 

WM_BUTTON2MOTIONSTART 12-16 

WM_BUTTON2UP 12-20 

WM_BUTTON2UP (in Frame Controls) 15-9 
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WM_BUTT0N3CLICK 12-9 

WM_BUTT0N3DBLCLK 12-12 

WM_BUTT0N3D0WN 12-17 

WM_BUTT0N3M0TI0NEND 12-18 

WM_BUTT0N3M0TI0NSTR 12-18 

WM_BUTT0N3UP 12-21 

WM_CALCFRAMERECT 12-22 

WM_CALCFRAMERECT (in Frame Controls) 15-9 

WM_CALCVALIDRECTS 12-22 

WM_CHAR 12-24 

WM_CHAR (Default Dialogs) 12-70 

WM_CHAR (in Entry Fields) 14-12 

WM_CHAR (in Frame Controls) 15-9 

WMCHAR (in List Boxes) 16-15 

WM_CHAR (in Multiline Entry Fields) 18-37 

WM_CHAR (in Notebook Controls) 25-18 

WM_CHAR (in Slider Controls) 26-16 

WM_CHAR (in Value Set Controls) 27-17 

WM_CHORD 12-25 

WM_CLOSE 12-26 

WM_CLOSE (Default Dialogs) 12-71 

WM_CLOSE (in Frame Controls) 15-10 

WM_COM M AND 11-3, 12-27, 15-10 

WM_COMMAND (Default Dialogs) 12-71 

WM_COMMAND (in Button Controls) 13-3 

WM_COMMAND (in Menu Controls) 17-4 

WM_CONTEXTMENU 12-28 

WM_CONTROL 11-3, 12-28 

WM_CONTROL (in Button Controls) 13-3 

WM_CONTROL (in Combination Boxes) 19-3 

WM_CONTROL (in Container Controls) 24-4 

WM_CONTROL (in Entry Fields) 14-3 

WM_CONTROL (in List Boxes) 16-2 

WM_CONTROL (in Multiline Entry Fields) 18-3 

WM_CONTROL (in Notebook Controls) 25-3 

WM CONTROL (in Slider Controls) 26-4 

WM_CONTROL (in Spin Button Controls) 21-2 

WM_CONTROL (in Value Set Controls) 27-5 

WM_CONTROL (Language Support Dialog) 12-83 

WM_CONTROL (Language Support Window) 12-80 

WM_CONTROLPOINTER 12-29 

WM_CONTROLPOINTER (in Container Controls) 24-5 

WM_CONTROLPOINTER (in Notebook Controls) 25-19 

WM_CONTROLPOINTER (in Slider Controls) 26-4 

WM_CONTROLPOINTER (in Value Set Controls) 27-6 

WM_CREATE 12-29 

WM_DDE_ACK 30-1 

WM_DDE_ADVISE 30-2 

WM_DDE_DATA 30-3 

WM_DDE_EXECUTE 30-3 

WM_DDE_INITIATE 30-5 

WM_DDE_INITIATEACK 30-5 

WM_DDE_POKE 30-6 

WM_DDE_REQUEST 30-7 

WM_DDE_TERMINATE 30-8 

WM_DDE_UNADVISE 30-9 

WM_DESTROY 8-109, 12-30 

WM_DESTROYCLIPBOARD 28-1 

WM_DRAWCLIPBOARD 28-2 

WM_DRAWITEM 12-31 

WM_DRAWITEM (in Container Controls) 24-6 

WM_DRAWITEM (in Font Dialog) 12-75 

WM_DRAWITEM (in Frame Controls) 15-10 

WM_DRAWITEM (in List Boxes) 16-3 

WM_DRAWITEM (in Menu Controls) 17-4 

WM_DRAWITEM (in Notebook Controls) 25-20 


WM_DRAWITEM (in Slider Controls) 26-5 
WM_DRAWITEM (in Value Set Controls) 27-6 
WM_ENABLE 12-31 

WM_ENABLE (in Button Controls) 13-10 
WM_ENABLE (in Multiline Entry Fields) 18-40 
WM_ENDDRAG 12-32 
WMENDSELECT 12-33 
WMERASEBACKGROUND 15-10 
WMERASEWINDOW 12-33 
WM_ERROR 12-34 
WM_FLASHWINDOW 15-11 
WM_FOCUSCHANGE 12-34 
WM_FOCUSCHANGE (in Frame Controls) 15-12 
WM_FORMATFRAME 12-35 
WM_FORMATFRAME (in Frame Controls) 15-12 
WM_HELP 11-3, 12-36 
WM_HELP (in Button Controls) 13-4 
WM_HELP (in Menu Controls) 17-5 
WM_HITTEST 12-37 
WM_HSCROLL 12-38 

WM_HSCROLL (in Horizontal Scroll Bars) 20-3 
WM_HSCROLLCLIPBOARD 28-2 
WM_INITDLG 12-38 
WM_INITDLG (Default Dialogs) 12-71 
WMJNITMENU 12-39 
WM_INITMENU (in Frame Controls) 15-13 
WMJNITMENU (in Menu Controls) 17-5 
WM_JOURNALNOTIFY 12-39 
WM_MATCHMNEMONIC 12-40 
WM_MATCHMNEMONIC (Default Dialogs) 12-71 
WM_MATCHMNEMONIC (in Button Controls) 13-10 
WM_MATCHMNEMONIC (in Static Controls) 22-4 
WMMEASUREITEM 12-41 
WM_MEASUREITEM (in Frame Controls) 15-13 
WM_MEASUREITEM (in List Boxes) 16-4 
WM MEASUREITEM (in Menu Controls) 17-5 
WM_MENUEND 12-41 
WM_MENUEND (in Menu Controls) 17-6 
WM_MENUSELECT 12-42 
WM_MENUSELECT (in Frame Controls) 15-13 
WM_MENUSELECT (in Menu Controls) 17-6 
WM_MINMAXFRAME 12-42 
WM_MINMAXFRAME (in Frame Controls) 15-4 
WM_MOUSEMOVE 12-43 

WM_MOUSEMOVE (in Multiline Entry Fields) 18-40 

WM_MOVE 8-508, 12-44 

WMJMEXTMENU 12-44 

WM_NEXTMENU (in Frame Controls) 15-14 

WM NEXTMENU (in Menu Controls) 17-7 

WM_NULL 12-45 

WM_OPEN 12-45 

WM_OWNERPOSCHANGE 15-14 

WM_PACTIVATE 12-46 

WM_PAINT 12-47 

WM_PAINT (in Frame Controls) 15-15 
WM_PAINT (Langauge Support Window) 12-80 
WM_PAINT (Language Support Dialog) 12-83 
WM_PAINTCLIPBOARD 28-3 
WMPCONTROL 12-47 
WM_PPAINT 12-48 

WMPPAINT (Language Support Dialog) 12-84 
WMPPAINT (Language Support Window) 12-81 
WMPRESPARAMCHANGED 12-48 
WM_PRESPARAMCHANGED (in Container 
Controls) 24-52 

WM PRESPARAMCHANGED (in Notebook 
Controls) 25-21 
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WM_PRESPARAMCHANGED (in Slider Controls) 26-17 
slider control 26-17 
value set control 27-18 
WM_PRESPARAMCHANGED (in Value Set 
Controls) 27-18 
WM_PSETFOCUS 12-49 
WM_PSIZE 12-49 
WM_PSYSCOLORCHANGE 12-50 
WM_QUERYACCELT ABLE 12-50 
WM_QUERYBORDERSIZE 15-15 
WM_QUERYCONVERTPOS 12-51 
WM_QUERY CON VERTPOS (in Button Controls) 13-10 
WMQUERYCONVERTPOS (in Entry Fields) 14-13 
WM_QUERYCONVERTPOS (in Frame Controls) 15-16 
WMQUERY CON VERTPOS (in List Boxes) 16-15 
WM_QUERYCONVERTPOS (in Menu Controls) 17-23 
WM_QUERYCONVERTPOS (in Scroll Bars) 20-8 
WM_QUERYCONVERTPOS (in Static Controls) 22-5 
WM_QUERYCONVERTPOS (in Title Bar Controls) 23-4 
WM_QUERYDLGCODE 12-72 
WM_QUERYFOCUSCHAIN 15-16 
WM_QUERYFRAMECTLCOUNT 15-17 
WM_QUERYFRAMEINFO 15-18 
WM_QUERYHELPINFO 12-52 
WM_QUERYICON 15-18 
WM_QUERYTRACKINFO 12-52 
WM_QUERYWINDOWPARAMS 12-53 
WM_QUERYWINDOWP ARAMS (in Button 
Controls) 13-11 

WM_QUERYWINDOWP ARAMS (in Entry Fields) 14-13 
WMQUERYWINDOWP ARAMS (in Frame 
Controls) 15-19 

WM_QUERYWINDOWPARAMS (in List Boxes) 16-16 
WM_QUERYWINDOWP ARAMS (in Menu Controls) 17-23 
WM_QUERYWINDOWP ARAMS (in Multiline Entry 
Fields) 18-41 

WM_QUERYWINDOWP ARAMS (in Scroll Bars) 20-8 
WM_QUERYWINDOWP ARAMS (in Slider Controls) 26-18 
slider control 26-18 
value set control 27-19 

WM_QUERYWINDOWP ARAMS (in Static Controls) 22-5 
WMQUERYWINDOWPARAMS (in Title Bars) 23-4 
WMQUERYWINDOWPARAMS (in Value Set 
Controls) 27-19 
WMQUIT 12-53 
WM_REALIZEP ALETTE 12-54 
WM_RENDERALLFMTS 8-109, 28-4 
WM_RENDERFMT 28-4 
WM_SAVE APPLICATION 12-55 
WM_SEM1 12-55 
WM_SEM2 12-56 
WM_SEM3 12-56 
WM_SEM4 12-57 
WM_SET ACCELT ABLE 12-57 
WM_SETBORDERSIZE 15-19 
WM_SETFOCUS 12-58 

WM_SETFOCUS (Language Support Dialog) 12-84 
WM_SETFOCUS (Language Support Window) 12-81 
WM_SETHELPINFO 12-58 
WM_SETICON 15-20 
WM_SETSELECTION 12-59 
WMSETWINDOWPARAMS 12-60 
WM_SETWINDOWPARAMS (in Button Controls) 13-11 
WM_SETWINDOWPARAMS (in Entry Fields) 14-13 
WM_SETWINDOWP ARAMS (in Frame Controls) 15-20 
WM_SETWINDOWP ARAMS (in List Boxes) 16-16 
WM_SETWINDOWPARAMS (in Menu Controls) 17-23 


WM_SETWINDOWP ARAMS (in Multiline Entry 
Fields) 18-42 

WM_SETWINDOWPARAMS (in Scroll Bars) 20-8 
WM_SETWINDOWPARAMS (in Slider Controls) 26-19 
slider control 26-19 
value set control 27-20 

WM_SETWINDOWPARAMS (in Static Controls) 22-5 
WM_SETWINDOWPARAMS (in Title Bar Controls) 23-4 
WM_SETWINDOWPARAMS (in Value Set Controls) 27-20 
WM_SHOW 12-60 
WM_SINGLESELECT 12-61 
WMSIZE 8-508, 12-61 
WM_SIZE (in Frame Controls) 15-20 
WM_SIZE (in Notebook Controls) 25-22 
WM_SIZE (in Value Set Controls) 27-20 
WM_SIZE (Language Support Dialog) 12-84 
WM_SIZE (Language Support Window) 12-81 
WM_SIZECLIPBOARD 28-5 
WM_SUBSTITUTESTRING 12-62 
WM_SYSCOLORCHANGE 12-63 
WM_SYSCOLORCHANGE (Language Support 
Dialog) 12-85 

WM SYSCOLORCHANGE (Language Support 
Window) 12-82 

WM_SYSCOM M AND 12-63, 13-4, 15-21, 17-7 
WM_SYSCOM M AND (in Title Bar Controls) 23-2 
WM_SYSVALUECHANGED 12-64 
WM_TEXTEDIT 12-65 
WM_TIMER 12-65 
WM_TRACKFRAME 12-66 
WM_TRACKFRAME (in Frame Controls) 15-22 
WM_TRACKFRAME (in Title Bar Controls 23-2 
WM_TRANSL ATE ACCEL 12-67 
WM_TRANSLATEACCEL (in Frame Controls) 15-23 
WM_TRANSLATEMNEMONIC 12-67 
WM_TRANSLATEMNEMONIC (in Frame Controls) 15-23 
WM_UPDATEFRAME 12-68 
WM_UPDATEFRAME (in Frame Controls) 15-23 
WM_VSCROLL 12-68 

WM_VSCROLL (in Vertical Scroll Bars) 20-3 
WM_VSCROLLCLIPBOARD 28-5 
WM_WINDOWPOSCHANGED 12-69 
WM_* messages 8-352 
WNDPARAMS A-125 
WndProc 10-4 

World Coordinates Bit Bit 5-567 
wpAddClockAlarmPage 9-53 
wpAddClockDateTimePage 9-54 
wpAddClockViewIPage 9-55 
wpAddClockView2Page 9-56 
wpAddCountryDatePage 9-57 
wpAddCountryNumbersPage 9-58 
wpAddCountryPage 9-59 
wpAddCountryTimePage 9-60 
wpAddDesktopLockupIPage 9-61 
wpAddDesktopLockup2Page 9-62 
wpAddDesktopLockup3Page 9-63 
wpAddDiskDetailsPage 9-64 
wpAddFileMenuPage 9-65 
wpAddFileTypePage 9-66 
wpAddFilelPage 9-67 
wpAddFile2Page 9-68 
wpAddFile3Page 9-69 
wpAddFolderBackgroundPage 9-70 
wpAddFolderlncludePage 9-71 
wpAddFolderSortPage 9-72 
wpAddFolderViewIPage 9-73 
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wpAddFolderView2Page 9-74 
wpAddFolderView3Page 9-75 
wpAddKeyboardMappingsPage 9-76 
wpAddKeyboardSpecialNeedsPage 9-77 
wpAddKeyboardTimingPage 9-78 
wpAddMouseMappingsPage 9-79 
wpAddMouseTimingPage 9-80 
wpAddMouseTypePage 9-81 
wpAddObjectGeneralPage 9-82 
wpAddProgramAssociationPage 9-83, 9-84 
wpAddProgramPage 9-85, 9-86 
wpAddProgramSessionPage 9-87, 9-88 
wpAddSettingsPages 9-89 
wpAddSoundWarningBeepPage 9-90 
wpAddSystemConfirmationPage 9-91 
wpAddSystemLogoPage 9-92 
wpAddSystemPrintScreenPage 9-93 
wpAddSystemWindowPage 9-94 
wpAddToObjUseLisl 9-95 
wpAllocMem 9-97 
WPCIock * A-125 
wpCIose 9-98 

wpcIsCreateDefau ItT emplates 9-240 
wpcIsFindObjectEnd 9-241 
wpcIsFindObjectFirst 9-242 
wpcIsFindObjectNext 9-244 
wpcIsInitData 9-246 
wpcIsMakeAwake 9-247 
wpcIsNew 9-249 
wpcIsQueryDefaultHelp 9-251 
wpcIsQueryDefauItView 9-252 
wpcIsQueryDetails 9-253 
wpcIsQueryOetailsInfo 9-254 
wpcIsQueryEditString 9-257 
wpcIsQueryError 9-258 
wpcIsQueryFolder 9-259 
wpcIsQuerylcon 9-260 
wpcIsQuerylconData 9-261 
wpcIsQuerylnstanceFilter 9-262 
wpcIsQuerylnstanceType 9-263 
wpcIsQueryObject 9-264 
wpcIsQueryOpenFolders 9-265 
wpcIsQuerySettingsPageSize 9-266 
wpcIsQueryStyle 9-267 
wpcIsQueryTitle 9-268 
wpcIsSetError 9-269 
wpcIsUnlnitData 9-270 
wpCnrlnsertObject 9-99 
wpCnrRemoveObject 9-101 
wpCnrSetEmphasis 9-102 
wpConfirmDelete 9-103 
wpCopiedFromTemplate 9-104 
wpCopyObject 9-105 
WPCountry * A-125 
wpCreateFromTemplate 9-106 
wpCreateShadowObject 9-107 
WPDataFile * A-125 
wpDelete 9-108 
wpDeleteAMJobs 9-109 
wpDeleteContents 9-110 
wpDeleteFromObjUseList 9-111 
wpDeleteJob 9-112 
WPDesklop * A-125 
WPDisk * A-125 
wpDisplayHelp 9-113 
wpDoesObjectMatch 9-114 
wpDragCell 9-115 


wpDraggedOverObject 9-1 16 
wpDragOver 9-118 
wpDrop 9-119 
wpDroppedOnObject 9-120 
wpEditCell 9-121 
wpEndConversation 9-122 
WPFileSystem * A-125 
wpFilterPopupMenu 9-123 
wpFindUseltem 9-125 
WPFolder * A-125 
wpFormalDragltem 9-126 
wpFree 9-127 
wpFreeMem 9-128 
wpHide 9-129 
wpHideFIdrRunObjs 9-130 
wpHoIdJob 9-131 
wpHoldPrinter 9-132 
wpInitData 9-133 
wpInsertPopupMenultems 9-134 
wpInsertSettingsPage 9-136 
wpIsCurrentDesktop 9-137 
WPJob * A-126 
WPKey board * A-126 
wpMenultemHelpSelected 9-138 
wpMenultemSelected 9-139 
wpModifyPopupMenu 9-140 
WPMouse * A-126 
wpMoveObject 9-141 
WPM_* values A-125 
WPObject * A-126 
WPOINT A-126 
wpOpen 9-142 
wpPaintCell 9-143 
WPPalette * A-126 
wpPopulate 9-144 
WPPrinler * A-126 
wpPrintJobNext 9-145 
wpPrintMetaFile 9-146 
wpPrintObject 9-147 
wpPrintPifFile 9-148 
wpPrintPlainTextFile 9-149 
wpPrintPrinterSpecificFile 9-150 
wpPrintUnknownFile 9-151 
WPProgramFile * A-126 
WPProgramGroup * A-126 
WPProgram * A-126 
wpQueryAssociationFilter 9-152, 9-153 
wpQueryAssociationType 9-154, 9-155 
wpQueryComputerName 9-156 
wpQueryConfirmations 9-157 
wpQueryContent 9-158 
wpQueryDefaultHelp . 9-159 
wpQueryDefauItView 9-160 
wpQueryOetailsData 9-161 
wpQueryError 9-163 
wpQueryFIdrAttr 9-164 
wpQueryFIdrDetailsClass 9-165 
wpQueryFIdrFlags 9-166 
wpQueryFIdrFont 9-167 
wpQueryHandle 9-168 
wpQuerylcon 9-169 
wpQuerylconData 9-170 
wpQueryLogicalDrive 9-171 
wpQueryNextlconPos 9-172 
wpQueryPaletteHelp 9-173 
wpQueryPalettelnfo 9-174 
wpQueryPrinterName 9-175 
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XYF_* values A-128 
XYWINSIZE A-127 

wpQueryStyle 9-181 
wpQueryTitle 9-182 
wpQueryType 9-183 
wpRedrawCell 9-184 
wpRefresh 9-185 
wpRegisterView 9-186 
wpReleaseJob 9-187 
wpReleasePrinter 9-188 
wpRender 9-189 
wpRenderComplete 9-190 
wpRestore 9-191 
wpRestoreData 9-192 
wpRestoreLong 9-193 
wpResto restate 9-194 
wpRestoreString 9-195 
WPRootFolder * A-126 
wpSaveData 9-196 
wpSaveDeferred 9-197 
wpSavelmmediate 9-198 
wpSaveLong 9-199 
wpSaveState 9-200 
wpSaveString 9-201 
wpScanSetupString 9-202 
wpSetAssociationFilter 9-204, 9-205 
wpSetAssociationT ype 9-206, 9-207 
wpSetComputerName 9-208 
wpSetOefaultHelp 9-209 
wpSetDefaultPrinter 9-210 
wpSetDefauItView 9-211 
wpSetError 9-212 
wpSetFIdrAttr 9-213 
wpSetFIdrDetailsClass 9-214 
wpSetFIdrFlags 9-215 
wpSetFIdrFont 9-216 
wpSetlcon 9-217 
wpSetlconData 9-218 
wpSetNextlconPos 9-219 
wpSetPalettelnfo 9-220 
wpSetPrinterName 9-221 
wpSetProgOetails 9-222, 9-223 
wpSetRealName 9-224 
wpSetShadowTItle 9-225 
wpSetStyle 9-226 
wpSetTitle 9-227 
wpSetType 9-228 
wpSetup 9-229 
wpSetupCell 9-233 
WPShadow * A-126 
wpShowPalettePointer 9-234 
WPSound * A-126 
WPSpooler * A-126 
WPSRCLASSBLOCK* A-126 
wpStartJobAgain 9-235 
wpSwitchTo 9-236 
WPSystem * A-127 
wpUnlnitData 9-238 
wpUnlockObject 9-237 
WRECT A-127 
Write Profile Data 6-19 
Write Profile String 6-21 
WS_* values 8-190, 12-2 


wpQueryProgDetails 9-176, 9-177 
wpQueryRealName 9-178 
wpQueryRootFolder 9-179 
wpQueryShadowedObject 9-180 
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